Markdown Basics: Format Your Texts With Ease

13 min read
  • This article teaches the basics of Markdown, a text-based approach to formatting texts without buttons or keyboard shortcuts.
  • Markdown works with any plain text file or app that supports it.
  • Several Markdown “flavors” offer distinct feature sets; this article covers only elements available in all common flavors.

Whenever I write anything that needs formatting—an article, an email, or even a book—I turn to Markdown. Markdown, which was invented by John Gruber and Aaron Swartz in 2004, is not an app, even though many apps support it. It’s a markup language, a syntax, a certain way of formatting your writings with nothing but a couple of symbols available on every keyboard. It’s as simple as starting a new line with a hyphen to indicate a list. Using Markdown is faster than moving your mouse to click a button and more intuitive than many keyboard shortcuts. And it’s easier to read and write than HTML.

Markdown, in fact, is writing HTML without writing HTML. That makes it suitable for the web; but it’s not limited to the Internet, either. With an app, you can export Markdown documents to HTML or a variety of other file types, such as RTF, PDF, and Microsoft Word. This is why I recommend you start any writing project in Markdown: It serves as a haven from which you can ship your texts anywhere you need them instead of locking them into proprietary software. Markdown is for those who enjoy speed, flexibility, and independence when writing.

Markdown 101

I’d like to introduce you to the basics of Markdown. You’ll learn the syntax to format perhaps most of your writings while building a solid foundation for more advanced techniques, which I’ll briefly discuss at the end of this article. All you need to get started with Markdown is a plain text file, which works on any operating system. The beauty of Markdown is that you can write it anywhere. Once it’s time to convert it to another format, you can still copy & paste it into one of the Markdown apps, so don’t worry about that right now.

The basic syntax

The idea behind Markdown is simple: You insert specific symbols into your text that carry special meaning. Once you’ve finished your text, and you’d like to export it, the Markdown interpreter analyzes it and replaces all those symbols with actual formatting. Imagine the symbols as sticky notes to a fictitious editor, labeled “Format this in italics,” “Add a link here,” or “This should be a footnote.”

Markdown is like HTML in the way tags work. Some are encapsulating, meaning they surround the text they format. Others stand by themselves. Contrary to HTML, Markdown tags consist of symbols but rarely letters or digits.

Text that you format in Markdown doesn’t look formatted as it would in a rich text editor, for example. For instance, text you set in italics doesn’t appear in italics at the time of writing. You can only tell from the asterisk on each side of the phrase that later it will be set in italics—be it in the final HTML code or PDF file. At export, the Markdown interpreter will remove all special symbols from your text (though they’ll remain in the original file). If you export to HTML, the interpreter will replace the symbols with proper HTML tags. If you export to Word or Rich Text, the text will be formatted as if you had clicked the respective buttons in the corresponding app.

That makes Markdown still a little harder to read than a rich text document because your brain will have to adjust to interpreting symbols such as asterisks not in their typical function but as vehicles of formatting. However, the readability is still improved compared to HTML, and, in contrast to RTF, you can see where the formatting begins and ends.

Paragraphs

The most basic element in Markdown is the paragraph. Contrary to HTML, Markdown doesn’t require paragraphs to be wrapped in a special tag, saving you plenty of time. Every block of text separated by a blank line from other blocks will be treated as a paragraph (unless you declared it to be something else).

Consider this excerpt from Dickens’ A Tale of Two Cities:1

And yet there is not in France, with its rich variety of soil and climate, a blade, a leaf, a root, a sprig, a peppercorn, which will grow to maturity under conditions more certain than those that have produced this horror.
    
Crush humanity out of shape once more, under similar hammers, and it will twist itself into the same tortured forms. Sow the same seed of rapacious license and oppression over again, and it will surely yield the same fruit according to its kind.

This translates to the following HTML code as generated by the Markdown interpreter:2

<p>And yet there is not in France, with its rich variety of soil and climate, a blade, a leaf, a root, a sprig, a peppercorn, which will grow to maturity under conditions more certain than those that have produced this horror.</p>
    
<p>Crush humanity out of shape once more, under similar hammers, and it will twist itself into the same tortured forms. Sow the same seed of rapacious license and oppression over again, and it will surely yield the same fruit according to its kind.</p>

Italics and bold

To set words or phrases in italics or bold, surround them with asterisks. Put one asterisk at each side to indicate italics and two asterisks to make it bold. Alternatively, you can use underscores.

Consider this line from Plato’s The Republic:3

Then we may *assume* that there are **three classes of men** — lovers of wisdom, lovers of ambition, lovers of gain?

This translates to the following HTML code:

Then we may <em>assume</em> that there are <strong>three classes of men</strong> — lovers of wisdom, lovers of ambition, lovers of gain?

Headings

Headings stand on their own lines. To differentiate them from paragraphs, start the line with one or more hash symbols. The number of hashes represents the level of the heading. It works like heading tags in HTML or heading levels in Microsoft Word and helps you create easy-to-follow documents with proper structure.

# The Republic
## The Republic
### The Republic
#### The Republic
##### The Republic
####### The Republic

This translates to the following HTML code:

<h1>The Republic</h1>
<h2>The Republic</h2>
<h3>The Republic</h3>
<h4>The Republic</h4>
<h5>The Republic</h5>
<h6>The Republic</h6>

Lists

The way you create lists in Markdown will perhaps seem familiar to you. They are one block of text, meaning they’re separated by blank lines from other blocks, and each line represents a list item. Every new item has to start with a list indicator, such as a hyphen for bullet point lists or a number followed by a period for ordered lists.

You can nest lists infinitely if you indent lines by four spaces for each level of indentation. This way, you can also combine ordered and unordered lists.

Then we may assume that there are three classes of men:
    
- lovers of wisdom, 
- lovers of ambition, 
- lovers of gain?
    
Then we may assume that there are three classes of men:
    
1. lovers of wisdom, 
2. lovers of ambition, 
3. lovers of gain?

This translates to the following HTML code:

<p>Then we may assume that there are three classes of men:</p>
    
<ul>
  <li>lovers of wisdom,</li>
  <li>lovers of ambition,</li>
  <li>lovers of gain?</li>
</ul>
    
<p>Then we may assume that there are three classes of men:</p>
    
<ol>
  <li>lovers of wisdom,</li>
  <li>lovers of ambition,</li>
  <li>lovers of gain?</li>
</ol>

Links

We differentiate two types of links in Markdown that differ in readability. The inline link and the reference link.

The problem with inline links is that the entire URL you’re linking to will be visible in the middle of your text. You enclose the word or phrase you want to link with square brackets and attach the URL to the end, right after the closing bracket. The URL itself is wrapped in parentheses.

Then we may assume that there are three classes of men — [lovers of wisdom](https://alexanderhetzel.com), lovers of ambition, lovers of gain?

The reference link, however, is much easier on the eyes. With this method, you enclose the link text in square brackets as well, but instead of attaching the URL, you define a unique ID. That can be anything from a single character to an entire phrase. The ID, however, is not wrapped in parentheses but in an individual pair of square brackets, just like the link text.

To define the URL, add a new line at the end of the document that starts with the ID (again, in square brackets) followed by a colon and the URL you want to link to. While this technique requires more symbols overall and a bit of scrolling, the extra effort pays off once you have to read or edit your works.

Then we may assume that there are three classes of men — [lovers of wisdom][low], lovers of ambition, lovers of gain?
    
(...)
    
[low]: https://alexanderhetzel.com

Both translate to the same HTML code:

Then we may assume that there are three classes of men — <a href="https://alexanderhetzel.com">lovers of wisdom</a>, lovers of ambition, lovers of gain?

Images

Images in Markdown work similar to links. We also differentiate two types: the inline image and the reference image. Since there’s no link text to wrap, we enclose the ALT text of the image (the text that’s shown if the image can’t be loaded) in square brackets. To tell the interpreter that this is an image and not a link, we add an exclamation point right before the opening bracket. Wrapped in parentheses, we attach the URL that refers to the image file right after the closing bracket. Note that without the exclamation point, an image would be indistinguishable from a link.

![Reflection by Mary Cassatt][https://tile.loc.gov/storage-services/service/pnp/ppmsca/38700/38723v.jpg]

To avoid cluttering our texts with long and distracting URLs, we can use the same reference format that helped us create cleaner links. Instead of attaching the URL in parentheses, add a unique ID in square brackets. At the end of the document, write this ID on a new line, enclosed in square brackets, and followed by a colon as well as the URL to the corresponding image file.

![Reflection by Mary Cassatt][refl]
    
(...)
    
[refl]: https://tile.loc.gov/storage-services/service/pnp/ppmsca/38700/38723v.jpg

Both translate to the same HTML code:

<img src="https://tile.loc.gov/storage-services/service/pnp/ppmsca/38700/38723v.jpg" alt="Reflection by Mary Cassatt">

Flavors and apps that suit your workflow

These are just the basics elements of a much richer syntax. Markdown comes in different “flavors” that add more functionality, such as footnotes, tables, mathematical notation, and more. Even the original version offers further elements like blockquotes, code blocks, and horizontal rules. You don’t need to concern yourself with these differentiations at this point, though. All you’ve learned in this article works with any of the Markdown flavors and apps.

The most popular apps, however, also support more extensive feature sets such as MultiMarkdown. It’s a good idea to choose the app based on the writing experience it provides and not by the specific implementation of Markdown. To get started, try Ulysses, iA Writer, Marked 2, Scrivener, Bear, and BBEdit—all of which have quite a unique approach to writing or, with Marked 2, displaying Markdown.

Apps like Ulysses, for example, try to hide a lot of the Markdown syntax to make texts easier to read. On the one hand, that sometimes deprives you of seeing additional information at a glance. (It’s also not the exact experience the inventors of Markdown had in mind.) On the other hand, it’s one of the cleanest Markdown experiences out there.

An app like iA Writer, in contrast, won’t hide any of the syntax from you, but it will still improve overall readability by coloring in the Markdown-specific symbols and previewing the formatting. Especially for beginners, this appears to be a healthy compromise between learning the syntax and not becoming overwhelmed by it.

The list of apps supporting Markdown is growing, and so is the number of Markdown enthusiasts. Perhaps, it will improve your writing process, too.

  1. Charles Dickens, A Tale of Two Cities (Random House, 2010), 398. Jump back.︎
  2. Throughout this article, I’ll show you what the Markdown syntax looks like when exported to HTML. If you don’t know HTML, you can ignore this. But if you do, this will make it a lot easier to grasp what the Markdown syntax does to a text when exported. I encourage you, though, to experiment with Markdown and export your texts to a format like PDF where you can see the formatting like a reader would experience it. Or even better, use an app that shows you a live preview, such as Markdown Live Preview, iAWriter, or Marked 2. Jump back.︎
  3. Benjamin Jowett, The Dialogues of Plato Translated into English with Analyses and Introductions by B. Jowett, M.A., (Oxford University Press, 1873), 2:411. Jump back.︎