A Markdown Cheat Sheet

It all started in 2004 when John Gruber introduced Markdown as "Email-style writing for the web."

Computing started with plain text, typewriter-style, with letters and symbols and little else. You couldn't bold or strikethrough text, or even change fonts and colors on the earliest software.

Much like typewriters, you were limited only by your creativity on early computers. You couldn't make your headlines bold, but you could type a line of dashes or equal symbols underneath to highlight them. Quotes could be offset with a greater-than symbol. Bullet lists could be added with dashes, ordered lists with numbers, periods, and lines. Slowly a syntax of symbols formed around early digital writing, especially in email, and we learned to read the symbols as formatting.

Then it all got complicated.

Rich text promised beauty, text formatted to your heart's content. What you see is what you get. Anyone could make a document look appealing or appalling.

HTML—especially when paired with CSS—promised consistency at the expense of simplicity. You would define your style, your colors, fonts, and more, in CSS. Then you'd write HTML with headings and bold text and any formatting you want—and paired with the CSS, it would look consistently great. Only, now you had to wrap <strong></strong> around every bit of text you wanted in bold, and woe betides if you forgot to close out the formatting.

CMS tools like WordPress tried to bridge the gap, with simple rich text editors that'd translate your text into HTML—and today, they're generally fine. Great, even, in writing-focused tools like Medium. That is until you write something in Word and paste it into WordPress—and it might be fine, or it might be irretrievably broken.

If only you could combine the consistency of HTML and the simplicity of rich text...

Gruber's inspiration was that email-style plain text formatting was pretty great, and if you could automatically convert that to HTML for web publishing and rich text for everything else, you might finally get the best of both worlds.

And that's why we have Markdown.

Everything you need to know about Markdown in 5 minutes or less.

Here's how Markdown works:

If you're writing plain text—normal sentences and paragraphs without anything extra—just write as normal. The only thing to note is you need to press enter twice after every paragraph, for a full blank line between every paragraph.

When you need formatting, then, you'll either put characters at the beginning of the line to change that whole line (for headings, quotes, and list items) or put characters before and after letters and words to format them specifically (for bold, italics, links, and more).

Here are the characters to remember (then check John Gruber's original Markdown documentation for more details and a bit of the thinking behind each choice):

Markdown Italics with single asterisks or underscores

Add either *one asterisk* or _one underscore_ before and after your text to italicize it.

Markdown Bold with double asterisks or underscores

Add either **two asterisks** or __two underscores__ before and after your text to make it bold.

Markdown Bold and Italics with three asterisks or underscores

Add either ***three asterisks*** or ___three underscores___ before and after your text to make it both bold and italicized (any combination of the two symbols will likely work, and you can mix it up—for example, add single asterisks around one word inside a bolded phrase to make it italicized and bold).

Markdown Strikethrough with tildes

Add ~~two tildes~~ around text to Strikethrough.

Markdown Underline ... with HTML, if you must

You shouldn't underline text on the web unless it's a link, as most readers will think your underlined text is a broken link. If you still decide you need to underline, use HTML.

Markdown Code blocks with backticks or tabs

Add `single backticks` around text to format it as code (to, for example, include sample HTML code in your copy instead of rendering the HTML code). Or, for multiple lines of code, start the first line with ``` three backticks and add the same three backticks after your final line of code (or indent each line of code—some Markdown apps will mark indented text as code, too).

Markdown Headings with hash or pound signs

Add # one hash sign to the beginning of a line of text to make it an H1 header, ## two hashes for H2, ### three hashes for H3, and so on. Everything you type after that will be formatted as a heading until you tap enter and start a new line. You can include italics and other formatting inside a header text, too.

Markdown Quotes with greater-than symbols

Add a > greater-than symbol at the beginning of a line to make a blockquote, where again you can include other formatting in the quoted text as well. Add it at the beginning of each subsequent line or paragraph to make longer, continuous quotes.

Markdown Line breaks with three asterisks or underscores

Add *** three asterisks or ___ three underscores on a separate blank line to add a line break, typically with a full line separating your paragraphs.

Markdown Lists with dashes

Add a - dash and space before your line of text to make it a bullet list (* a single asterisk or + plus sign works equally well), then press return once and add another dash, space, and text to add the next bullet item to your list. Or, for an indented bullet point and a nested list, press return then tab for your next line—that will work at least in some Markdown apps. Press return twice and add a full blank line between your list to go back to writing normal text.

Markdown Numbered lists with numbers and periods

Add a 1. number, period, and space then your text—and add your following points in sequential lines with their correct number.

Markdown Checkbox with brackets and dashes

A fun extra that's not official Markdown, but some Markdown apps support: Make a checklist with a bullet list and square brackets for an unfinished checklist, like - [ ] this. Then, to check off the item, add an ex to the middle of the square brackets like - [x] this.

Markdown Links with brackets and parenthesis

Links take two steps: [square brackets around your linked text then parenthesis around](https://your.link/). That'll leave you with just the text in the brackets, linked to the domain in the parenthesis. (Tip: if you want to add anything extra to your link, such as target="_blank" to open the link in a new tab, you're best off adding HTML to your Markdown instead.) Or, a hack: You can simply write \https://link.com/\ with less than and greater than symbols around your link to show the domain in your text and link it in one go.

Markdown Images with exclamation marks and links

Most Markdown apps let you insert images almost the same as links: Add an ! exclamation mark first, then the alt text, then a link to your image, like . If you want to center your image, customize your image style, and more, you're again best off adding HTML to your Markdown (or, check your Markdown app: Some, such as Kirby CMS, include custom image markup text to add more customizations without resorting to HTML).

Markdown Tables with pipes, dashes, and spaces ... or HTML

One other unofficial Markdown thing that many apps support is tables—but they're unwieldily and, as you may have guessed by now, you're almost better off just writing HTML. Gruber said it himself in the original Markdown concept: No tables: use HTML.. If you want to make plain text tables, add a | pipe symbol between each cell, dashes underneath the header cells, and spaces to make everything look as good in plain text as it should in the final copy. Here's an example—use with caution:

| header 1      | header 2            |
|---------------|---------------------|
| something     | something else      |
| another point | and one final point |

And that's it.

If you remember how to add bold (double asterisks), italics (single asterisks), links (brackets then parenthesis), quotes (greater than), headers (hash marks), and (dashes) unordered lists, odds are that's all the Markdown you'll need 95% of the time.

For that remaining 5% of the time, keep this around as a reference the next time you need to add something less frequently used. And if you need anything else—superscripts, subscripts, multi-column text, formatted images, fancy tables, and more—odds are it'll be easier to add some HTML. Write Markdown when it makes sense, HTML for everything else.

What you might need is a little practice to make sure you remember your Markdown. If so, sign up for our free five-email course that'll remind you a bit of Markdown and get you to practice it, every day, for a week:

Happy writing!

→ For a bit more on Markdown, here's the history of Markdown with details on how plain text formatting evolved, including early Markdown-style italics in early Peanuts comics.