Learn Markdown: Structure, Syntax, and Conventions

Content on the Web needs to be presented in HTML format. Many web publishing tools (such as blogging software and CMSs) convert your content (text, images and so on) into HTML for you. But there are many situations where you want to write HTML content yourself … and marking up content with HTML tags manually is laborious and not really viable. Enter Markdown.

Markdown is an easy, frictionless way of writing content for the Web and the perfect way for developers to create documentation. It lets you structure and format documents easily using simple, text-based markup, which then gets converted into HTML for you — all from within your favorite text editor.

If you’re not already using Markdown, now might be the time to begin. You can learn the basics in minutes, and with ongoing use, the syntax will become second nature. In this article, we’ll encourage you to start simply and show you how to use Markdown for a range of common tasks when creating content.

Let’s dive in!

What Is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. It’s easy to write, easy to read, and can be easily turned into HTML. It was primarily designed for writing for the Web.

It has rapidly grown in popularity and is now used in contexts never envisaged by its creator. But it’s not perfect. It has limits, especially as it leaves out formatting for a lot of HTML elements you might need to use (such as tables). It can also be a little ambiguous.

As a result, a range of variants has been created to deal with these problems:

• CommonMark attempts to standardize Markdown and make it less ambiguous, contradicting some of the original syntaxes in the process.
• GitHub Flavored Markdown (GFM) extends CommonMark and is used when creating documentation on GitHub.
• MultiMarkdown added new syntax for tables, footnotes, citations, and more.
• Pandoc extends Markdown for multiple output formats (not just HTML) and supports document metadata, footnotes, tables, superscript, subscript, and more.

Some web services and Markdown editors support the syntax of some of these variants or even use their own version of Markdown. Fortunately, they all support the original Markdown syntax, and that’s what we’ll focus on in this article.

Learning Markdown

The best way to learn Markdown is simply to start. Pick a use case and begin, whether that’s creating a blog post, working on documentation, or just adding some basic formatting to your notes. Pick up the syntax piece by piece as you need it.

You can use your favorite text editor, or choose one of the many apps designed to work with Markdown. Markdown editors can ease the learning process because they allow you to preview your formatting inline or in a separate pane. That means you can see at a glance whether or not you’re using the correct syntax.

Personally, I use Marked 2 to preview Markdown files on my Mac. It’s a commercial product, but of course you can find lots of free plugins for your editor of choice. You can also edit and preview Markdown files online using Markdown Live Preview and StackEdit.

For help choosing the right Markdown editor, refer to these roundup articles:

• The Best Markdown Editors for Mac
• The Best Markdown Editor for Windows
• The Best Markdown Editor for Linux

Structuring Documents

Markdown lets you add structural elements to your document, such as headings (h1, h2, h3 etc.). There are a few ways to add headings in Markdown . My favorite is to prefix a heading with hashes #, one for each level of heading:

# Heading 1

## Heading 2

### Heading 3

etc.

And this is body text.

The hashes move lower-level headings further to the right, so they appear indented. You can optionally use the same number of hashes at the end of the line to close the headers:

### Heading 3 ###

There’s a second way, though I don’t see it used as often. You can create two levels of headings by underlining the H1 headings with equals = symbols and H2 headings with hyphens -:

Heading 1 or Title
==================

Heading 2
---------

Sections of a document can be separated using horizontal rules (<hr />), or lines. You create these in Markdown using three (or more) hyphens -, asterisks *, underscores _ or equals = signs. Place them alone on a line, with blank lines on either side:

Brief introduction.

===

# Chapter 1

Lots of text.

---

# Chapter 2

Some more text

---

Lists are another important structural element. Unordered lists (<ul>) are created by beginning the line with an asterisk *, plus + symbol, or hyphen -, followed by a space or tab, then the text:

* this
* is
* an
* unordered
* list

+ this
+ is
+ too

- and
- so
- is
- this

Choose whichever symbol suits you. You can switch between these symbols and the end result will be the same. I tend to use asterisks or hyphens.

Ordered lists (<ol>) are numbers followed by periods. The numbers don’t necessarily have to be in order. Either of these will work:

1. this
2. is
3. an
4. ordered
5. list

1. and
1. so
1. is
1. this

The Markdown editors I use automatically continue a list when pressing return.

If you want to start a line with a number and a period without starting a list, you need to escape the period with a backslash \:

2020\. A year we'll never forget.

Finally, paragraphs of normal text are separated by one or more blank lines:

This will be formatted as an HTML paragraph.

And so will this.

Basic Text Formatting

Basic text formatting includes bold and italics. Underline doesn’t tend to be used on the Web, since it’s how hyperlinks are formatted, so it isn’t supported by Markdown. If you really want to use it, just use <u> HTML tags. (This is worth noting more generally. Where Markdown doesn’t support a particular type of HTML element, you can just use the HTML markup instead. There’s just one caveat: any Markdown syntax inside HTML tags won’t get parsed.)

Words in italics are delimited by a single asterisk (*) or underscore (_):

this is *italics*
and so is _this_

Words in bold are delimited by a double asterisk (**) or underscore (__):

this is **bold**
and so is __this__

Some people prefer to choose either underscore or italics. For example, I normally use asterisks for both **bold** and *italics*.

Others prefer to differentiate bold and italics by using different symbols, like this: **bold** and _italics_:

_You **can** also combine them_

Blockquotes and Code Blocks

Blockquotes can be created by beginning a line with a greater than (>) symbol, just like older email clients quoted previous messages:

> This is a blockquote. Single paragraphs
> can be continued like this on a second line.
> 
> Multiple paragraphs can be quoted by using a
> line with a single greater than symbol.

My preferred way is a little simpler and only uses the greater than symbol at the beginning of each quoted paragraph. This works whether you use an editor that hard-wraps or soft-wraps paragraphs:

> You can also blockquote a paragraph
by placing a single greater than symbol at
the beginning of each paragraph.

> Nested blockquotes are also possible
> > Like this.

Code blocks are created by indenting every line by at least four spaces or one tab:

This is a normal paragraph:

    This is a code block.

But other flavors of Markdown prefer to use backticks. For example, Ulysses uses two backticks at the beginning of a line for a code block:

``This is a code block.

GitHub flavored Markdown uses three backticks to begin and end the code block. Obsidian, Bear, and some other Markdown editors follow the same convention:

```
This is a code block.
```

To embed that code block in a code block, I wrapped it in quadruple backticks. On GitHub, you can optionally include the language if you want syntax highlighting:

```ruby
This is Ruby code with syntax highlighting.
```

Code can be displayed within a paragraph by using single backtick delimiters:

This code `<bold>` will be displayed, not interpreted.

Links and Images

Links and images use a combination of square brackets [] and parentheses (). For links, you surround the anchor text with square brackets, followed immediately by the URL in parentheses:

This is a [link to a web page](https://url.com).

If you like, you can add a title to a link. It will appear as a tooltip when you hover over the link. Enclose the title in quotes after the URL and inside the parentheses:

This is a [link to a web page](https://url.com "This title will appear as a tooltip").

Another method for marking up links is known as reference linking. These look like footnotes in the Markdown document but will be converted to standard links when exported to HTML. The goal here is to make the Markdown document more readable.

Instead of linking directly to the URL, you use a label in square brackets. Then elsewhere in the document (typically at the bottom), you associate that label with a URL:

This is a [link to a web page][mylabel].

Then at the end of the document …

[mylabel]: https://url.com "Optional title"
or
[mylabel]: <https://url.com> (Optional title)

Labels are not case sensitive and can consist of letters, numbers, spaces, and punctuation.

Images use a similar syntax but start with an exclamation mark (!):

![Alt text](https://imageurl.com)

If you like, you can add a title enclosed by quotes inside the parentheses.

![Alt text](https://imageurl.com "This is a title")

You can also use reference links for images:

![Alt text][mylabel]

[mylabel]: https://imageurl.com "This is a title"

GitHub Flavored Markdown Extras

GitHub Flavored Markdown is used by many developers, and it provides additional syntax to make it more capable. Here are some examples.

Strikethrough is an additional text formatting option that’s achieved with double tildes (~~):

This is how you do ~~strikethrough~~.

Task lists can be created using - [ ] for unchecked items, and - [x] for checked items:

- [ ] This item is unchecked
- [x] This item is checked

You can create a table by using pipes and hyphens to draw the lines. Three or more hyphens --- create the headers, and pipes | create columns:

| Heading 1 | Heading 2 | Heading 3 |
| --------- | --------- | --------- |
| some text | more here | and this  |
| some more | this too  | and this  |

This looks better when the columns align, but it’s not necessary. Either way, the table will be created correctly when exporting to HTML:

| Heading 1 | Heading 2 | Heading 3 |
| --------- | --------- | --------- |
| some text | more here | and this |
| some more | this too | and this |

Creating a table like this gets quite tedious, especially if you need to edit the contents of the cells. Fortunately, there are online table generators that simplify the process.

Final Words

Markdown isn’t for everyone, but there’s a lot to like. Personally, I appreciate that it’s open, easy to learn, and doesn’t lock you into using a particular program.

If you’ve made it to the end of this article, it might be the right tool for you, too. Dive in and start using it. Learn the syntax piece by piece as you need it, and before you know it, it will become second nature.

Make sure you download our free printable Markdown cheat sheet. It covers core Markdown syntax, some extended syntax, tools for processing Markdown and other resources.