Markdown That You Might Not Know

I write every one of my blog posts in Markdown. Markdown is easy to store, easy to edit and above all easy to implement. I, specifically, use a variation of Github Flavored Markdown with a few of my own additions that make my workflow easier - for example, I can use [tweet tweetIdHere] to embed a tweet in one of my posts. Github Flavored Markdown (GFM) is the most common Markdown Spec to see implemented around the internet, likely due to the fact it was developed by Github and is therfore open source. That being said, there are many features of GFM that I think more people should be using but aren't. You could say that I read the spec so that you don't have to.

I often find myself linking to the same url multiple times in a blog post. Usually a spec that I'm writing about such as GFM in this case. You can reuse links by defining your refrences at the bottom of the file (which can include a link title) and then refrencing the link anywhere else in the page using its reference [text][refrenceName]. This means that if you later have to update your link, you can update it in a single location rather than having to update every instance.

2. Strike Through

We all know that *text* and _text_ can be used to emphisise text (usually by making it italic) or that **text** can be used to make text strongly emphisised (often by making it bold). Did you know, however, that you can use the tilde (~) character to strike through text. Either within a wider paragraph or as a block scoped element. Strike Through ("Crossed Out" for my fellow citizens of the UK) text, is useful for showing that text has changed or is no longer relevant.

3. Setext headings

While I personally prefer the more common ATX headings (The ones that use #) in markdown, Setext headings are also supported in GFM implementations. The underlining can be any length with Setext headings and I think it makes a heading look reasonable both when rendered as well as when in plain text. One more cool thing about Setext headings is that they can span multiple lines according to the spec - although Typora, in which I write this, didn't support that unfortunately.

4. Syntax Highlighted Code

This is a fairly well known feature of markdown, but I've included it on this list as I often see examples of markdown that haven't used syntax highlighting. By adding the name of a "language" after your blocked code tags, you can enable syntax highlighting for that language in your code block. This supports a wide variety of languages including: JavaScript, C++, HTML or even Markdown Itself.

5. HTML in Markdown

While many things can be done with pure markdown, ocasionally you want to do something that just doesn't have the syntax available. You might want to add specific css styles to a paragraph or use some obscure (or outdated) html element such as a marquee tag. Markdown supports embedded HTML. Not the entire HTML Spec, as some tags are removed for security, but enough of it to allow much greater flexibility than otherwise would be available.

The tags you cannot use are:

  • <title>
  • <textarea>
  • <style>
  • <xmp>
  • <iframe>
  • <noembed>
  • <noframes>
  • <script>
  • <plaintext>

6. YAML Front Matter

While YAML Front Matter isn't actually part of the GFM Spec, you might still have come across it within a commonly used feature of Github. Github Pages is built on top of Jekyll. Jekyll is a static site system written in ruby that uses markdown for blog posts and pages. It uses YAML Front Matter at the top of those markdown files to support meta data such as blog post categories and page titles. It's incredibly useful to be able to store arbitrary data in your markdown file as it means that while you might store markdown in a database for your live site, it can be modified offline in its entirety. Just remember that depending on where you use this markdown file, it may or may not be rendered as normal text.

Conclusion

Markdown is incredibly flexible. There's a reason that I and so many other sites use it as our primary method of storing text information. I'm not going to pretend that this article has covered any of the basics of Markdown ( There are plenty of resources for that ). I do hope, however, that you learned something that you didn't know about beforehand and that you consider using what you learned in future.

github issue

Webmentions

What's this?

This site uses Webmentions to handle likes, comments and other interactions. To leave a comment, you can reply on Twitter, GitHub, or Reddit. While the site will count likes from any source, only twitter likes are currently displayed in the facepile above.