Markdown provides a simple way of formatting rich text, which will help us write beautifully formatted content for the web. All you need is to understand its few simple rules. To show you what a powerful writing tool it can be, this is a Markdown guide to the basics.

Fun fact: this post was originally written in Markdown!

What is Markdown?

Markdown is a plain text formatting syntax for writers. It allows you to quickly write structured content for the web, and converts it in to structured HTML.

Back in 2004, John Gruber of Apple came up with the idea after becoming frustrated by writing long, laborious HTML tags to properly format his content. He devised a simple writing system which would make web based documents both easier to write, and easier to read in their raw state.

You might have seen this syntax before on sites like Reddit, where users are able format their posts with it.

Here’s an example of Markdown:

The _quick_ brown fox, jumped **over** the lazy [dog](https://en.wikipedia.org/wiki/Dog).

This block of code becomes:

The quick brown fox, jumped over the lazy dog.

With just a couple of extra characters, Markdown makes rich document formatting quick and beautiful.

Why Markdown?

At first glance, Markdown may just seem like an obfuscated alternative to an interface-based text formatting tool similar to what is found in programs like Microsoft Word. As you go through this article, you will see that while the basics of Markdown are fairly simple, it soon reveals itself to have many benefits to those can who stick with and become experienced at it.

Markdown’s concise syntax allows you to format your text with a quick button press or two. Once you get used to it, you’ll be seamlessly formatting your content as your write it! And all this without ever once removing your hands from the keyboard. This leads to easily achieving a flow state when writing.

For those already versed in HTML, it might surprise you to know that writing HTML inside your Markdown is actually a totally valid thing to do! While Markdown only covers a subset of HTML elements (namely those specific to writing text-driven content), you are completely welcome to use plain old HTML for anything outside of the possibilities of Markdown. More on this later…

Markdown is a tool that rewards knowledge and experience, and does so while being very simple to read and write at its core.

Markdown Basics

Okay, so let’s get in to writing some actual Markdown now.

Markdown was designed to be easily readable by humans. You will find that most of its rules are simple and intuitive.

Here are some basic elements, and likely also the ones you’ll use most often:

Headings

# Heading 1

## Heading 2

### Heading 3

Headings in Markdown are any line which starts with a # symbol. The number of hashes indicates the level of the heading. One hash is converted to an h1, two hashes to an h2 and so on. There are a total of 6 levels which you can make use of – but for most writing, you’ll rarely ever need more than 3.

Text

_italic_
**bold**
**_bold-italic_**
[link](https://example.com)

If you want to emphasize a word a little bit, wrap it in asterisks. For something that needs more emphasis: double asterisks. If you really want to drive the point home, use triple asterisks. If you want, you can also use _ underscores – they’re completely interchangeable.

To add a link: wrap the text which you want to be linked in square brackets, followed by the URL to be linked to in parenthesis. An easy way to remember this one is to think of it like turning a word into a button. [button] and (place to go when the button is clicked) combine to form a link.

Images

![Fawn](https://i.imgur.com/ZHF2NmE.jpg)

Markdown images have exactly the same formatting as a link, except they’re prefixed with a !. This time, the text in brackets is the alt text – or the descriptive text for the image.

In most Markdown editors, you don’t have to write this code out. They will provide a tool to allow you to upload an image and insert this code automatically. After that, it will appear in your document.

Lists

- Milk
- Bread
  - Wholegrain
- Butter

1. Tidy the kitchen
2. Prepare ingredients
3. Cook delicious things

Lists are a formatting nightmare in HTML, but Markdown lists are incredibly easy to manage. For a bullet list, just prefix each like with a * – or - or + and they will be converted to dots. You can also create nested lists; just indent a line with 4 spaces and it will be nested under the line above.

• Milk
• Bread
  • Wholegrain
• Butter

For numbered lists, do exactly the same thing, but with numbers.

Quotes

> I shot the sheriff, but I did not shoot the deputy.

becomes:

I shot the sheriff, but I did not shoot the deputy.

Prefixing the line with a > converts it into a block-quote.

How am I supposed to remember all this?

I know, I know, it’s a lot. But really, even after only a couple of hours, you’ll find you are able to be very productive, very quickly. Personally, 95% of the time I just need headings, links, images, lists, and bold/italics.

In the meantime, feel free to find a Markdown editor. That can help ease the transition.

Markdown Cheat Sheet

Intermediate Markdown Formatting

Okay, you’ve got the basics, so let’s move on to some optional advanced stuff.

Horizontal Rules

---

Want to throw-down a quick divider in your article to denote a visual separation between different sections of text? No problem. 3 dashes produce:

A sleek <hr> element.

Code Snippets

`console.log("This is an inline code snippet.");`

becomes:

console.log("This is an inline code snippet.");

Indenting your text with four spaces turns it in to a code block. Like this:

function printMessage() {
  console.log(
    "Woah, so that's how I've been making code blocks this whole time!"
  )
}

Escaping

\*literally\*

What if you literally want to type *literally* – without it appearing in italics? Escaping Markdown characters with a back-slash \ allows you to use any characters which might be getting accidentally converted into HTML.

Embedding HTML

<button>
  Big Fat Button
</button>

I mentioned earlier that HTML is a perfectly valid thing to use in Markdown when you want to do one of the many things HTML is capable of, but is traditionally outside the scope of Markdown.

So you can drop in any HTML, sharing button, JavaScript snippet or iFrame you like and it will work on the page just as normal.

What’s Next?

Practice these steps to become a pro:

1. Start with writing your first Markdown document and get a feel for the basics. It comes more quickly than you might think!
2. Use HTML whenever you want advanced formatting, having this power available to you means you can really do (almost) anything.