A quick and easy guide to Markdown

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!

Headingspermalink

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 #:

# I am a heading level 1

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

### I am a heading level 3 

Paragraphspermalink

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.

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. 

Bold textpermalink

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

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

Italic/emphasised textpermalink

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

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

Strikethrough/deleted textpermalink

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

A paragraph with some ~~strikethrough text~~.

Linkspermalink

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:

[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:

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

Imagespermalink

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:

![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)

Blockquotespermalink

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

For example, this is a one line blockquote:

> This is a one line quote

And this is multiple lines:

> 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

Horizontal rulepermalink

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

Inline codepermalink

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

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

Code blockspermalink

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

```
Some preformatted text. 

On multiple lines.
```

Listspermalink

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:

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:

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 -:

- 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:

- 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

HTML elements are supported toopermalink

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:

## 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>

Wrapping uppermalink

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 readingpermalink

• Extended Markdown syntax
• MDX. MDX powers this and all posts on Piccalilli!
• Mastering Markdown. A free 10 part video course by Wes Bos.
• A comparison of syntax extensions in Markdown flavors
• A more comprehensive guide

Playgroundpermalink

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.