A quick and easy guide to Markdown

Published on by Andy Bell

So many Markdown guides are either too complicated or really hard to read. I thought I’d try to fix that with a super simple, clear guide.

This guide is designed to help everyone with Markdown, even if they have never written it before. It is deliberately simple. There’s links to further resources and learning at the end of the article.

I’m not going to spend ages explaining what Markdown is or how it works because there’s already great resources for that. Instead, I’m going to break down the most important aspects of Markdown with quick and easy snippets so you can start composing great content!

Headings

Markdown enables you to to compose HTML heading elements by using a # character as a prefix. All you need to remember is that the number of #’s as a prefix represents the heading level.

For example, if you want a <h1> element, you add one #:

markdown
# I am a heading level 1

If you want a <h3> element, you add three #’s:

markdown
### I am a heading level 3

See the Pen Markdown headings by Andy Bell (@andy-set-studio) on CodePen.

Paragraphs

To create a <p> — which is a paragraph element — add a new line between sections of text. Make sure you press Enter without holding down the shift key.

markdown
This is a paragraph of text which can contain as many words as you like.

This is another paragraph of text, seperated with a new line. You don’t have to do anything else other than create a new line between paragraphs.

See the Pen Markdown paragraphs by Andy Bell (@andy-set-studio) on CodePen.

Bold text

To make text bold, wrap it in ** characters on each side of the text like so:

markdown
This is some text with **a section of bold content**.

See the Pen Markdown bold text by Andy Bell (@andy-set-studio) on CodePen.

Italic/emphasised text

This is very similar to making text bold. Instead of two * characters, you only use one for italic/emphasised text.

markdown
This is some text with a *section of italic text*.

See the Pen Markdown italic text by Andy Bell (@andy-set-studio) on CodePen.

Strikethrough/deleted text

To apply a strikethrough to your text, Markdown allows you to generate a <del> tag by wrapping it in ~~, like so:

markdown
A paragraph with some ~~strikethrough text~~.

See the Pen Markdown strikethrough/deleted text by Andy Bell (@andy-set-studio) on CodePen.

To apply a link, wrap the text in square brackets. That’s starting with an [ character and finishing with a ] character. This should then be immediately followed with the URL you want to link to in parentheses — also known as round brackets ().

For example, let’s say I want to create a link to the BBC:

markdown
[The BBC](https://www.bbc.co.uk/) is a public service broadcaster in the UK.

Markdown can also automatically wrap URLs in links for you too. Say for example, you wanted to write https://www.bbc.co.uk that links to https://www.bbc.co.uk, wrap the link in an opening < and closing > like so:

markdown
Visit <https://www.bbc.co.uk> for more info.

See the Pen Markdown links by Andy Bell (@andy-set-studio) on CodePen.

Images

Embedding an image with an <img> element is very similar to links. The only difference is the square brackets contain the alternative text and the parentheses contains a URL to the image. You also need to add a ! character as a prefix to the square brackets:

markdown
![A 'subscribe' button appears to sit on top of an email input which has a placeholder value of '[email protected]'. The form is labelled 'Enter your email to sign up for our newsletter'](https://piccalilli.imgix.net/images/blog/floating-signup-form-pattern.jpg)

See the Pen Markdown images by Andy Bell (@andy-set-studio) on CodePen.

Blockquotes

For every line of your blockquote (<blockquote>) — including new lines — use a > character as the prefix.

For example, this is a one line blockquote:

markdown
> This is a one line quote

And this is multiple lines:

markdown
> This is a quote that is broken into multiple lines 
> 
> Notice how the line above is just a > character. This allows the Markdown processor to put both lines of the quote in the same `<blockquote>` element

See the Pen Markdown blockquotes by Andy Bell (@andy-set-studio) on CodePen.

Horizontal rule

You can apply a horizontal rule with three asterisks (***), three hashes (---) or three underscores (___).

See the Pen Markdown horizontal rule by Andy Bell (@andy-set-studio) on CodePen.

Inline code

You might have noticed in the blockquotes example we were using the ` character. Wrapping text in these characters renders them in a <code> element.

markdown
If you want space between elements in CSS, use the `margin` property.

See the Pen Markdown inline code by Andy Bell (@andy-set-studio) on CodePen.

Code blocks

You can also generate multiline code blocks by adding ``` on the line before your text and ``` on the line after your text like so:

markdown
```
Some preformatted text. 

On multiple lines.
```

See the Pen Markdown code blocks by Andy Bell (@andy-set-studio) on CodePen.

Lists

You can compose ordered (<ol>) and unordered lists (<ul>) with Markdown.

If you want to compose an ordered list, start each line with a number, followed by a dot, like so:

markdown
1. I am list item one
2. I am list item two
3. I am list item three
4. I am list item four

You can also use the same number each time:

markdown
1. I am list item one
1. I am list item two
1. I am list item three
1. I am list item four

To generate an ordered list, start each line with a -:

plaintext
- I am list item one
- I am list item two
- I am list item three
- I am list item four

Lastly, you can nest list items like so:

plaintext
- I am list item one
  - I am another list inside list item one
- I am list item two
  1. I am an ordered list, nested in an unordered list
  1. Notice how I can still use 1. on every item too
- I am list item three
- I am list item four

See the Pen Markdown lists by Andy Bell (@andy-set-studio) on CodePen.

HTML elements are supported too

Lastly, you can write good ol’ fashioned HTML in Markdown! For example, you could compose a table with Markdown, but maintaining that would be a nightmare.

An easier way is to render a HTML table element instead:

markdown
## A level 2 heading 

Some paragraph text with *emphasis* and **bold**. 

<table>
  <thead>
    <tr>
      <th>Month</th>
      <th>Savings</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>January</td>
      <td>$250</td>
    </tr>
    <tr>
      <td>February</td>
      <td>$80</td>
    </tr>
    <tr>
      <td>March</td>
      <td>$420</td>
    </tr>
  </tbody>
</table>

See the Pen Markdown HTML elements by Andy Bell (@andy-set-studio) on CodePen.

Wrapping up

We’ve only just scratched the surface with Markdown here, but that level of knowledge should support the vast majority of people wanting to work with Markdown in their content.

Learning Markdown has so many benefits too. It’ll make you more efficient in Notion, Slack and Trello to name just a few services that support Markdown syntax.

You can go much deeper by reading up on the following links, but if you’ve been sent this link as a quick reference, just keep enjoying the simple — yet powerful — benefits of Markdown!

Further reading

Playground

Thanks to our friends at CodePen — who’s pen editor supports markdown — here’s a handy, editable playground that you can practice what you’ve learned in this guide.

See the Pen Markdown playground by Andy Bell (@andy-set-studio) on CodePen.