Page Body

A Markdown Primer

Hypertext Markup Language (HTML) is the markup language that underlies the World Wide Web (WWW). If you need to create web content, you can directly write HTML, with or without the assistance of an Integrated Development Environment (IDE) or an advanced text editor (e.g., Atom or VSCodium). The markup you write will remain relatively legible, but there will be many symbols related to HTML's syntax that obscure your content.

In 2004, John Gruber (with some assistance from Aaron Swartz) created the Markdown language in order to have a more legible markup language that could be easily converted to HTML.

Markdown is intended to be as easy-to-read and easy-to-write as is feasible.

Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters — including Setext, atx, Textile, reStructuredText, Grutatext, and EtText — the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.

To this end, Markdown’s syntax is comprised entirely of punctuation characters, which punctuation characters have been carefully chosen so as to look like what they mean. E.g., asterisks around a word actually look like *emphasis*. Markdown lists look like, well, lists. Even blockquotes look like quoted passages of text, assuming you’ve ever used email.

John Gruber

Since then, Markdown has become the de facto standard for creating web content.

Markdown is:

  • supported by most Content Management Solutions (CMSes) and text editors
  • used for project readme files and in myriad messaging forums
  • the basis of many open source projects' documentation and the underlying content format for most static site generators
  • available in popular support tools (e.g., Zendesk)

If you do any kind of writing or development work, you should consider becoming conversant with Markdown.

Standardization

Markdown was released as an informal specification and, unlike HTML, there is not a single Markdown standard. This has not stopped Markdown fans from trying to create one.

Here are some of the available Markdown flavors:

CommonMark
A strongly defined, highly compatible specification of Markdown created by John MacFarlane, David Greenspan, Vicent Marti, Neil Williams, Benjamin Dumke-von der Ehe, and Jeff Atwood. CommonMark was created to provide a standard unambiguous syntax specification for Markdown, along with a suite of tests to validate Markdown implementations against the specification.
GitHub Flavored Markdown (GFM)
GitHub's formal specification of Markdown, based on CommonMark. GFM is mostly the same as CommonMark, except for how it implements certain elements (e.g., tables, strikethrough) as extensions, i.e., features that are supported in GitHub user content and are not specified in the CommonMark specification. Also, it uses a customized parser (i.e., the Markdown processor that converts Markdown text into HTML).

There are many more flavors.

If you want to simultaneously compare how Markdown text will be processed by different Markdown implementations, try babelmark3.

Usage

Markdown was designed to complement HTML, and its syntax covers the basic HTML elements you will most frequently use as you write content.

As Gruber states:

Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text.

Some implementations of Markdown decided to incorporate more complicated HTML structures (e.g., tables). However, Markdown documents can directly incorporate HTML code. For more consistent results, you are probably better off writing these elements in HTML.

Again, from Gruber:

For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.

The only restrictions are that block-level HTML elements — e.g. <div>, <table>, <pre>, <p>, etc. — must be separated from surrounding content by blank lines, and the start and end tags of the block should not be indented with tabs or spaces. Markdown is smart enough not to add extra (unwanted) <p> tags around HTML block-level tags.

The Basics

Markdown files are plain text files that end with a .md extension. This is useful because GNU/Linux provides a plethora of tools that can work with plain text, ranging from command line utilities (e.g., sed, gawk), to powerful text editors that have specialized functionality for dealing with Markdown.

Paragraphs

A paragraph is one or more consecutive lines of text that are separated by one or more blank lines, where a blank line is a line that contains only spaces or tabs. Paragraphs should not be indented.

Markdown HTML Output
Similique dolorum voluptas maxime et quidem. Ipsum ut sed id repellat. Nihil quisquam consequatur nisi quia.

Distinctio molestiae voluptatum est quas nesciunt qui impedit accusantium. Et aut quas sit saepe non illo est pariatur. Et dolores quis dolorum praesentium. Cum doloribus non modi doloribus.
<p>Similique dolorum voluptas maxime et quidem. Ipsum ut sed id repellat. Nihil quisquam consequatur nisi quia.</p>

<p>Distinctio molestiae voluptatum est quas nesciunt qui impedit accusantium. Et aut quas sit saepe non illo est pariatur. Et dolores quis dolorum praesentium. Cum doloribus non modi doloribus.</p>

Similique dolorum voluptas maxime et quidem. Ipsum ut sed id repellat. Nihil quisquam consequatur nisi quia.

Distinctio molestiae voluptatum est quas nesciunt qui impedit accusantium. Et aut quas sit saepe non illo est pariatur. Et dolores quis dolorum praesentium. Cum doloribus non modi doloribus.

Line Breaks

A line break (i.e., <br />) can be created at the end of a line by adding two or more spaces and pressing Enter.

Markdown HTML Output
This is the first line.
This is the second line.
<p>This is the first line.<br />
This is the second line.</p>

This is the first line.
This is the second line.

Headings

You can create headings by adding the number sign (#) and a space before your heading text. For example, the heading for this post's section in Markdown is ### Headings.

Markdown HTML Output
# Heading level 1 <h1>Heading level 1</h1>

Heading level 1

## Heading level 2 <h2>Heading level 2</h2>

Heading level 2

### Heading level 3 <h3>Heading level 3</h3>

Heading level 3

#### Heading level 4 <h4>Heading level 4</h4>

Heading level 4

##### Heading level 5 <h5>Heading level 5</h5>
Heading level 5
###### Heading level 6 <h6>Heading level 6</h6>
Heading level 6

Blockquotes

Add a > in front of a paragraph to turn it into a blockquote. For example, > Similique dolorum voluptas maxime et quidem. Ipsum ut sed id repellat. Nihil quisquam consequatur nisi quia. will be rendered like this:

Similique dolorum voluptas maxime et quidem. Ipsum ut sed id repellat. Nihil quisquam consequatur nisi quia.

If a blockquote has multiple paragraphs, add a > on the blank line(s) between the paragraphs.

> Similique dolorum voluptas maxime et quidem. Ipsum ut sed id repellat. Nihil quisquam consequatur nisi quia.
>
> Distinctio molestiae voluptatum est quas nesciunt qui impedit accusantium. Et aut quas sit saepe non illo est pariatur. Et dolores quis dolorum praesentium. Cum doloribus non modi doloribus.

The blockquote above will be rendered as:

Similique dolorum voluptas maxime et quidem. Ipsum ut sed id repellat. Nihil quisquam consequatur nisi quia.

Distinctio molestiae voluptatum est quas nesciunt qui impedit accusantium. Et aut quas sit saepe non illo est pariatur. Et dolores quis dolorum praesentium. Cum doloribus non modi doloribus.

If you want a blockquote within a blockquote, add >> in front of the nested blockquote.

> Similique dolorum voluptas maxime et quidem. Ipsum ut sed id repellat. Nihil quisquam consequatur nisi quia.
>
>> Distinctio molestiae voluptatum est quas nesciunt qui impedit accusantium. Et aut quas sit saepe non illo est pariatur. Et dolores quis dolorum praesentium. Cum doloribus non modi doloribus.

Similique dolorum voluptas maxime et quidem. Ipsum ut sed id repellat. Nihil quisquam consequatur nisi quia.

Distinctio molestiae voluptatum est quas nesciunt qui impedit accusantium. Et aut quas sit saepe non illo est pariatur. Et dolores quis dolorum praesentium. Cum doloribus non modi doloribus.

Emphasis

You can emphasize text by making it italic or bold.

Italic

To italicize text, add an asterisk (or underscore) to both sides of the text in question.

Markdown HTML Output
Similique *dolorum voluptas* maxime et quidem. Similique <em>dolorum voluptas</em> maxime et quidem. Similique dolorum voluptas maxime et quidem
Similique _dolorum voluptas_ maxime et quidem. Similique <em>dolorum voluptas</em> maxime et quidem. Similique dolorum voluptas maxime et quidem

Bold

To bold text, add two asterisks (or underscores) to both sides of the text in question.

Markdown HTML Output
Similique **dolorum voluptas** maxime et quidem. Similique <strong>dolorum voluptas</strong> maxime et quidem. Similique dolorum voluptas maxime et quidem
Similique __dolorum voluptas__ maxime et quidem. Similique <strong>dolorum voluptas</strong> maxime et quidem. Similique dolorum voluptas maxime et quidem

Italic and Bold

To have text be both italicized and bold, add three asterisks (or underscores) to both sides of the text in question.

Markdown HTML Output
Similique ***dolorum voluptas*** maxime et quidem. Similique <strong><em>dolorum voluptas</em></strong> maxime et quidem. Similique dolorum voluptas maxime et quidem
Similique ___dolorum voluptas___ maxime et quidem. Similique <strong><em>dolorum voluptas</em></strong> maxime et quidem. Similique dolorum voluptas maxime et quidem

Lists

You can have ordered and unordered lists.

Ordered Lists

To create an ordered list, add line items with a number, followed by a period and a space.

Markdown HTML Output
1. First item
2. Second item
3. Third item
4. Fourth item
<ol>
  <li>First item</li>
  <li>Second item</li>
  <li>Third item</li>
  <li>Fourth item</li>
</ol>
  1. First item
  2. Second item
  3. Third item
  4. Fourth item

Nested Ordered Lists

You can have an ordered list inside of an ordered list by indenting the list items for the nested ordered list.

Markdown HTML Output
1. First item
2. Second item
3. Third item
  1. First indented item
  2. Second indented item
4. Fourth item
<ol>
  <li>First item</li>
  <li>Second item</li>
  <li>Third item</li>
  <ol>
    <li>First indented item</li>
    <li>Second indented item</li>
  </ol>
  <li>Fourth item</li>
</ol>
  1. First item
  2. Second item
  3. Third item
    1. First indented item
    2. Second indented item
  4. Fourth item

Unordered Lists

To create an unordered list, add dashes (or asterisks, or plus signs) and a space in front of your list items.

Markdown HTML Output
- First item
- Second item
- Third item
- Fourth item
<ul>
  <li>First item</li>
  <li>Second item</li>
  <li>Third item</li>
  <li>Fourth item</li>
</ul>
  • First item
  • Second item
  • Third item
  • Fourth item
* First item
* Second item
* Third item
* Fourth item
<ul>
  <li>First item</li>
  <li>Second item</li>
  <li>Third item</li>
  <li>Fourth item</li>
</ul>
  • First item
  • Second item
  • Third item
  • Fourth item
+ First item
+ Second item
+ Third item
+ Fourth item
<ul>
  <li>First item</li>
  <li>Second item</li>
  <li>Third item</li>
  <li>Fourth item</li>
</ul>
  • First item
  • Second item
  • Third item
  • Fourth item

Nested Unordered Lists

Like with ordered lists, you can create an unordered list inside of another unordered list by indenting it.

Markdown HTML Output
- First item
- Second item
- Third item
  - First indented item
  - Second indented item
- Fourth item
<ul>
  <li>First item</li>
  <li>Second item</li>
  <li>Third item</li>
  <ul>
    <li>First indented item</li>
    <li>Second indented item</li>
  </ul>
  <li>Fourth item</li>
</ul>
  • First item
  • Second item
  • Third item
    • First indented item
    • Second indented item
  • Fourth item

Links can be created by enclosing the anchor text in square brackets, immediately followed by the URL in parentheses. For example, here is a link to Daring Fireball:

[Daring Fireball](https://daringfireball.net/) is the site of Markdown's creator.

The above sentence's Markdown output looks like this:

Daring Fireball is the site of Markdown's creator.

You can add an optional title to a link by enclosing it in quotes and placing it after the URL:

[Daring Fireball](https://daringfireball.net/ "Daring Fireball: Home") is the site of Markdown's creator.

Daring Fireball is the site of Markdown's creator.

An email address can be transformed into a link by enclosing it in angle brackets:

<admin@siliconsoul.org>

The above email address's Markdown output is:

admin@siliconsoul.org

You can emphasize links the same way that you emphasize normal text.

_[Daring Fireball](https://daringfireball.net/ "Daring Fireball: Home")_ is the site of Markdown's creator.
**[Daring Fireball](https://daringfireball.net/ "Daring Fireball: Home")** is the site of Markdown's creator.

Daring Fireball is the site of Markdown's creator.
Daring Fireball is the site of Markdown's creator.

If you find Markdown's inline links to be too cluttered, you can use reference links, instead.

Code

To denote code, surround it with tick marks (`).

Markdown HTML Output
Similique `dolorum voluptas` maxime et quidem. Similique <code>dolorum voluptas</code> maxime et quidem. Similique dolorum voluptas maxime et quidem

If you want to display multiple lines of code, you can denote a fenced code block by using three tick marks (```).

```
Eaque eligendi voluptas et aut dolor explicabo id. Aut minus in debitis quo est rerum velit tempore. Possimus et consequatur quaerat quos voluptatem voluptas iste ut.

Omnis animi neque voluptatem pariatur eos molestiae dolorem ex. Maxime quos quo nisi molestiae quisquam. Dolor dolorum atque est esse aut harum est.
```

The above Markdown text will output as follows:

Eaque eligendi voluptas et aut dolor explicabo id. Aut minus in debitis quo est rerum velit tempore. Possimus et consequatur quaerat quos voluptatem voluptas iste ut.

Omnis animi neque voluptatem pariatur eos molestiae dolorem ex. Maxime quos quo nisi molestiae quisquam. Dolor dolorum atque est esse aut harum est.

Horizontal Rule

A horizontal rule can be created using three or more dashes (---), asterisks (***), or underscores (___).

---

***

___

All of the above will output as:


Images

To create an image, add an exclamation mark (!), followed by the image's alt text in square brackets ([]), and the path of the image URL in parentheses (()). Optionally, you can add a quoted image title after the URL inside the parentheses. Essentially, it is just a Markdown link, prepended with an exclamation mark.

![John Gruber](https://cdn.vox-cdn.com/thumbor/nWvpYHHW2RL1DafZxWegPGx6-hQ=/0x35:614x444/1200x800/filters:focal(0x35:614x444)/cdn.vox-cdn.com/assets/773573/addison-bw.jpeg "John Gruber")

The above Markdown text will output:

John Gruber

You can add a link to an image by enclosing your Markdown image text in square brackets, and then adding the link in parentheses.

[![John Gruber](https://cdn.vox-cdn.com/thumbor/nWvpYHHW2RL1DafZxWegPGx6-hQ=/0x35:614x444/1200x800/filters:focal(0x35:614x444)/cdn.vox-cdn.com/assets/773573/addison-bw.jpeg "John Gruber")](https://www.theverge.com/2011/11/1/2529005/5-minutes-on-the-verge-john-gruber)

John Gruber

Escaping Characters

If you want to display a character that is used by Markdown to format text, you can escape it with a backslash (\) in front of the character in question.

\- Without a backslash, this would be an unordered list item.

The above Markdown text is output as:

- Without a backslash, this would be an unordered list item.

These are the characters that you should be able to escape:

Character Name
\ Backslash
` Tick Mark
* Asterisk
_ Underscore
{} Curly Braces
[] Square Brackets
() Parentheses
# Number Sign
+ Plus Sign
- Minus Sign / Hyphen
. Period
! Exclamation Point
| Pipe

Resources

There are many online resources where you can learn more about Markdown, and experiment with or test your Markdown text.

Daring Fireball

You can find the original Markdown description and syntax summary from its creator, John Gruber, on his site, Daring Fireball. Also, Gruber has a helpful dingus, where you can both preview how your Markdown text will be rendered and obtain its HTML source code.

CommonMark

The CommonMark site has a quick reference card and 10 minute Markdown tutorial for getting up to speed with Markdown basics. Like on Daring Fireball, CommonMark offers a dingus where you can test your Markdown text and get a preview or HTML source code.

Markdown Guide

Markdown Guide has a nice collection of the tools and platforms that support Markdown, as well as a handy reference guide that can be downloaded in a variety of formats.

Avatar

Enjoyed this post?

Subscribe to the feed for the latest updates.