Making A Mark
Markdown Is Everywhere. Time to Learn How to Use It.
Writing is one of those skills that you should double down on in 2020 and beyond. To make your writing process easier, faster, and more flexible, John Gruber and Aaron Swartz invented Markdown over 16 years ago. Markdown is neither an app nor a programming language; it’s a syntax that you can use everywhere you input text, even in a plain text document. Learn how to use it and why you should write articles, e-mails, and even books in Markdown from now on.
Why all of your texts should start in Markdown
Markdown allows you to format your text without using your mouse to click on a button or remembering complex keyboard shortcuts. It goes far beyond making words bold or italic. You can also add headings, lists, links, images, and even tables and code blocks to your writings just by adding a few additional characters to your text.
Almost every serious writing app has built-in Markdown support. The same goes for many notes apps, e-mail apps, and even WhatsApp (though it uses its own knock-off format). But the list of benefits continues:
- You can write Markdown everywhere. Even though a plethora of Markdown apps exists, you don’t need more than a regular writing app for starters. Any plain text file will do the trick. You might not be able to export your text into any useful format from that app, but you can write and save your Markdown-formatted text anywhere. Later, you can still use other tools to actually interpret the text you’ve written. Furthermore, Markdown is entirely platform and device independent, so you can use it everywhere.
- It doesn’t interrupt your workflow. One of the greatest productivity killers is switching to your mouse. Your hands should be on the keyboard whenever possible. Clicking a button to italicize text or create a list, therefore, disturbs your writing process and costs you precious time. Learning keyboard shortcuts can be a possible solution, but they might vary across apps. Markdown, by contrast, only requires you to type a few extra symbols on your keyboard.
- Markdown is easily readable and lightweight. Markdown adds additional characters to your texts, but altogether your text remains readable. Even if you don’t use a specific Markdown app that fades out the extra symbols, a plain text file with Markdown formatting is still easy to comprehend.
- It can be exported to plenty of formats. One of the most prominent benefits of Markdown is the possibility to export your texts into various formats, such as HTML, DOC, PDF, RTF, or EPUB. The available formats depend on the app you use to interpret Markdown.
- Write once, publish again and again. With Markdown, you write and format a text only once. Afterwards, you can export it to any format as often as you like. Writing a blog article? Your editor might want a DOC file to use the track changes feature. The person you’ve interviewed for that article is probably best served with a PDF before they give their consent to publication. And finally, the blog post needs to be published, so you should ideally have it in HTML code or plain text as well. That’s not a problem with Markdown. You write it once and export it as often as necessary without ever having to reformat it again.
- It sticks with you. When you write in Microsoft Word, your text remains stuck there. You’re confined to the formats it offers. If you copy your writings to plain text files for preservation, you relinquish their formatting. Markdown, however, is nothing but text. You can save or paste it anywhere, and it will stay as is.
- Your texts will likely survive the end of humanity. Nobody can say anything about the supposed lifespan of Markdown. But since Markdown is just simple text, you can store it in a plain text file, which will probably survive until the end of time.
How Markdown works
To begin writing in Markdown, you usually don’t need to prepare anything. You can just start typing in any app that can work with regular text.
In most cases, the Markdown syntax surrounds the element it manipulates. Let’s look at a simple example in which we make one word bold:
The quick brown fox jumps over the **lazy** dog.
By surrounding the word “lazy” with two asterisks on either side, you signal the Markdown interpreter to consider this word bold. Later, when you export your text as a PDF or HTML file, the interpreter will account for that and actually make this word bold according to the file format. That means that in Microsoft Word, the word would appear in bold letters, while it would be surrounded by <strong> and </strong> in HTML.
A couple of Markdown elements work with symbols that are placed only to the left or right of the text, but we’ll get to that soon enough.
Which is the right flavor?
Besides the original Markdown, several “flavors” have been invented to expand Markdown with additional features, such as footnotes or tables. Some writing apps support only the original flavor, while other apps offer broader support. For details, see your app’s documentation.
You can install the processors directly on your computer, but this isn’t usually recommended. Be aware of the various flavors and their differences, and then choose a writing app that integrates your preferred processor.
The following flavors are widely used:
- (Original) Markdown. The basic Markdown processor is still used by a lot of apps. Invented by John Gruber and Aaron Swartz.
- Github Flavored Markdown. This flavor supports tables but not footnotes and is generally aimed towards programmers, who need extensive code editing capabilities. Invented by Github.
- MultiMarkdown. A very popular flavor that supports footnotes, tables, and tables of contents, but also many other features, such as mathematical expressions and math blocks. Invented by Fletcher T. Penney.
- Pandoc. Pandoc features footnotes, tables, and mathematical expressions, but not tables of contents. As a parser for many document formats, it goes far beyond Markdown. Invented by John MacFarlane.
Their feature sets differ not only in terms of quantity but also in the way they’re implemented. Unfortunately, that means that a different flavor might make it necessary to learn a slightly different syntax. However, you will usually use only one flavor, so that shouldn’t make too big a difference.
The basic elements of Markdown
The following elements are just the tip of the Markdown iceberg, but they’re the ones you’ll probably use most frequently.
To produce paragraphs in Markdown, you don’t need to do anything other than hitting the Enter key twice. Just like this.
Every paragraph separated by at least one blank line will be recognized as such—no additional symbols needed. This feature also makes it easier to convert existing text into HTML because you don’t need to wrap every paragraph in <p></p> tags by hand. Great when you have pre-written blog posts in Google Docs.
There are two ways to italicize text: with asterisks (*) or underscores (_). Put one of them on each side of the part of text you want to emphasize, but make sure not to mix them.
The quick brown fox jumps over the *lazy* dog.
The quick brown fox jumps over the _lazy_ dog.
Bold text behaves similarly to italic text. Insert two asterisks (*) or underscores (_) on each side of the text you want to make bold.
The quick brown fox jumps over the **lazy** dog.
The quick brown fox jumps over the __lazy__ dog.
You can denote headings in an even easier way than emphasized text. You put the number sign (#) in varying numbers to the left side of the headline:
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
You are free to put them on both sides, but that’s only necessary if the headline spans across line breaks. Long headlines that span over multiple lines automatically (without specific line breaks) don’t require the symbols on both sides.
# Heading 1 #
## Heading 2 ##
### Heading 3 ###
#### Heading 4 ####
##### Heading 5 #####
###### Heading 6 ######
It’s almost impossible that you’ve never created a Markdown list before because it requires only a hyphen (-), an asterisk (*), a plus (+), or a number (1.) at the beginning of a new line.
- Foxes are quick
- Dogs are lazy
- Cats are greedy
* Foxes are quick
* Dogs are lazy
* Cats are greedy
+ Foxes are quick
+ Dogs are lazy
+ Cats are greedy
1. Foxes are quick
2. Dogs are lazy
3. Cats are greedy
The first three lists are identical and will be properly formatted as unordered lists by the interpreter. The last one, by contrast, produces an ordered list.
- Foxes are quick
- There’s a study on that
- They’re probably faster than you
- Dogs are lazy
- Cats are greedy
1. Foxes are quick
1. There’s a study on that
2. They’re probably faster than you
2. Dogs are lazy
3. Cats are greedy
To make nested lists, indent each item of the sublist by four spaces. If an item of that sublist has a sublist as well, indent those items by four more spaces, and so on.
You might ask yourself what Markdown has to do with this. Haven’t you been using this method to create lists for decades, after all? The difference is that Markdown actually interprets these lists. If you copy & pasted these lists to a Word document, they would just be plain text with hyphens or numbers at the beginning of the line. Exporting such a list through a Markdown processor, however, would result in text that is actually formatted as a list. Just if you had clicked on the list icon in Microsoft Word or Google Docs. And exporting them to HTML would magically transform them into equally well-formatted lists with all the <ul>, <ol>, and <li> that you need. Which comes in particularly handy when they’re nested, which is tedious to do by hand in HTML.
Now that you know the basics of Markdown, it pays off to dive a little deeper into the syntax. The following elements are slightly more complex, but you’ll need them on a regular basis as well.
We differentiate two types of links in Markdown: the inline link and the reference link. Both produce the exact same output, but their syntax differs slightly.
1. Inline Link:
Don’t worry, [Hidden Emphasis](https://hiddenemphasis.com) has your back.
With inline links, you put the text you want to link in square brackets and add the URL in parentheses immediately thereafter.
2. Reference Link:
Don’t worry, [Hidden Emphasis][he] has your back.
The reference link is much shorter and easier to read, but it requires an additional reference to that link. Even though you can put it anywhere, it’s best practice to put a list of link references at the end of the chapter or the entire document.
The “he” in the example above serves as an identifier for the link. You define it once when setting up the link in the text and then reference it later. That means you need a different identifier for each link in your document.
Both variations will produce the following HTML output:
Don’t worry, <a href="https://hiddenemphasis.com">Hidden Emphasis</a> has your back.
Luckily, images work very similarly to links. You can choose between inline images and reference images.
1. Inline Image:
![Hidden Emphasis Logo](https://hiddenemphasis.com/img/hidden-emphasis-logo.png)
Put the ALT text of the image in square brackets and follow it with the link in parentheses.
2. Reference Image:
![Hidden Emphasis Logo][logo]
Just as with links, the reference image is two-fold. First, specify the link through an ID, then reference the same ID elsewhere in your text and define a link to the image. Beware of the exclamation mark (!)—it differentiates the image syntax from the link syntax but is not used in the reference again.
Both versions will produce the following HTML output:
<img src="https://hiddenemphasis.com/img/hidden-emphasis-logo.png" alt="Hidden Emphasis Logo">
You can define blockquotes in Markdown the same way you quote text in an e-mail: by starting every new line (or paragraph) with a greater-than sign (>).
1. Per line
> You can put the greater-than sign
> before every single line of your text
> and it will become a blockquote
2. Per paragraph
> However, you could also just put it once
in front of every paragraph. That way, you
can give your fingers a rest.
> And call it a day.
If you want to nest quotes, Markdown makes that possible as well. Just increase the quote level by putting two or more > at the beginning of the line.
In Markdown, you can produce a horizontal rule or divider by placing three or more hyphens (-), asterisks (*), or underscores (_) on a new line. Separate them with spaces if you prefer.
* * *
- - -
_ _ _
All of the above will generate the same dividing line. No politician could draw that any better.
This is where the original Markdown warranty ends. However, the different flavors of Markdown allow for additional elements that can be useful in your daily work.
Footnotes are easy to notate once you understand how links and images work. They come in two flavors as well: inline footnotes and reference footnotes.
1. Inline Footnotes
Sahlman says, “Taking advantage of arbitrage opportunities is a viable and potentially profitable way to enter a business.”[^William A. Sahlman, “How to Write a Great Business Plan,” Harvard Business Review 75 (July–August 1997), 103.]
Add the text of the footnote in square brackets right where you want the footnote to appear, starting with a circumflex (^). Markdown will automatically compile a list of footnotes at the end of the document.
2. Reference Footnotes
Sahlman says, “Taking advantage of arbitrage opportunities is a viable and potentially profitable way to enter a business.”[^harvard]
[^harvard]: William A. Sahlman, “How to Write a Great Business Plan,” Harvard Business Review 75 (July–August 1997), 103.
While the inline version of links and images might be suitable, inline footnotes clutter your text and make it unreadable. Which is why I highly recommend using reference footnotes.
When using reference footnotes, you specify the footnote through an identifier that you reference later in the text (in this example called “harvard”). This looks much neater and more closely resembles the way footnotes work.
Footnotes are supported by many Markdown flavors, including MultiMarkdown and Pandoc.
Tables call for a more artistic approach. This might be slightly more tedious than creating a table in a software like Microsoft Word, but especially for beginners, it’s much easier than creating an HTML table by hand.
|Unit|Relation to SI units|
|inch|≡ 0.0254 m|
|foot|≡ 0.3048 m|
|yard|≡ 0.9144 m|
[Unit Conversion Table]
To denote a table row, start the line with a pipe symbol (|). Separate each column with another pipe symbol, and end the row with yet another one. Each new line represents a new row. The separator row (three hyphens per cell) separates the header row from the content rows. The separator will not be displayed itself; it has only an organizational function (letting Markdown know that the table head ends there).
End the table with a caption in a pair of square brackets immediately below your last row.
Tip: To extend a cell over multiple columns, just leave out the pipe symbols in between.
Tables are supported by many Markdown flavors, including MultiMarkdown and Pandoc.
Writing apps that support Markdown
While you don’t need an app to start writing in Markdown, you will ultimately need an interpreter to convert your text into the desired formats. The easiest way to do this is simply to use an app that supports Markdown.
Ulysses is an elaborate writing suite that relies heavily on Markdown. For example, this article was written in Ulysses. It offers wide support for Markdown elements, including footnotes. This software is targeted at more serious writers, as its features go far beyond supporting Markdown.
iA Writer is a lightweight writing tool; however, it offers an even more thorough Markdown integration than does Ulysses in certain ways. It supports footnotes, but in contrast to Ulysses, you can also add tables and tables of contents to your writings.
Marked 2 is not exactly a writing app; it’s a Markdown previewer. That means you can use any writing app you like, and Marked 2 will show you a fully formatted preview of your text in a separate window (you can see it in action in the video above). It supports a wide variety of Markdown processors and is probably the most flexible option on the market.