Markdown Cheat Sheet: All the Markdown You Need

This Markdown cheat sheet covers all the Markdown syntax you’ll actually use, from headings, bold text, and lists to tables, footnotes, and GitHub alerts. The quick reference table below fits on one screen. Further down, every element gets its own short section with the Markdown source and the rendered result.

Everything works in standard Markdown (CommonMark) unless the Notes column says otherwise. “GFM” means GitHub Flavored Markdown: it works on GitHub and in many, but not all, other tools.

Element	Markdown syntax	Notes
Headings	# H1 ## H2 … ###### H6	Space after the #
Paragraph	Blank line between blocks of text
Line break	Two spaces or \ at the end of a line	Or <br>
Bold	**bold** or __bold__
Italic	*italic* or _italic_
Bold and italic	***bold italic***
Strikethrough	~~strikethrough~~	GFM
Blockquote	> quote	Nest with >>
Ordered list	1. Item
Unordered list	- Item or * Item
Nested list	Indent to line up with the parent’s text	2 spaces after -, 3 after 1.
Task list	- [x] Done - [ ] To do	GFM
Link	[text](https://example.com)
Reference link	[text][id] [id]: https://example.com
Autolink	<https://example.com>	Bare URLs: GFM
Link to a heading	[text](#heading-text)	Anchor ids vary per platform
Image		Size: use <img width>
Linked image	[](https://example.com)
Inline code	`code`
Code block	```python … ```	Language is optional
Table	| A | B | |---|---| | 1 | 2 |	GFM
Horizontal rule	--- or ***	Blank line above it
Escape a character	\*not italic\*
Footnote	Text[^1] [^1]: The note.	GFM
Alert	> [!NOTE] > Text	GitHub only
Collapsible section	<details><summary>Title</summary> … </details>	HTML
Comment	<!-- hidden --> or [//]: # (hidden)
HTML	<kbd>Ctrl</kbd>, <sup>2</sup>	Platforms may filter tags
Emoji	Paste 😄 or :smile:	Shortcodes: GitHub and some others

To keep this cheat sheet brief, I link to more detailed articles where a topic deserves more room, like Markdown tables, code blocks, and README.md files. New to Markdown? Start with my Markdown introduction.

Headings

Headings (many people call them headers) structure your document. There are two ways to create them: with hash signs or by underlining the text.

Hashes: H1 to H6

Start a line with one to six # characters, followed by a space. The number of hashes is the heading level, from H1 (the largest) to H6 (the smallest):

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

These become the HTML <h1> to <h6> elements and look roughly like this:

Don’t forget the space: #Heading is plain text in CommonMark and on GitHub. Use only one H1 per document, usually the title, and don’t skip levels. That’s better for readers, screen readers, and search engines.

Underlined headings

Alternatively, you can ‘underline’ a heading with = (H1) or - (H2) characters. It’s more typing, but some people like how it stands out in plain text. This only works for H1 and H2:

Heading 1
=========

Heading 2
---------

Any number of = or - characters works, but I match the length of the text so it looks tidy.

Paragraphs and line breaks

To start a new paragraph, leave a blank line between two blocks of text. A single line break (pressing Enter once) does not start a new line in the output: Markdown joins those lines into one paragraph.

This is the first paragraph.
This line is joined with the line above.

This is a second paragraph.

The result:

This is the first paragraph. This line is joined with the line above.

This is a second paragraph.

If you want a line break inside a paragraph (a <br> in HTML), you have three options:

1. End the line with two or more spaces. This works everywhere, but the spaces are invisible and some editors strip them.
2. End the line with a backslash \. This is part of CommonMark and GFM, and it’s my favorite because you can see it.
3. Use an HTML <br> tag, if your Markdown renderer allows HTML.

Roses are red,\
Violets are blue,<br>
Markdown is simple
And so are you.

The result (the last two lines are joined because there’s no line break between them):

Roses are red,
Violets are blue,
Markdown is simple And so are you.

One exception: in GitHub issues, pull requests, and comments, a single Enter does create a line break. In .md files in a repository, it doesn’t. My article on Markdown line breaks covers every platform and edge case.

Emphasis (bold, italic)

You can emphasize text by making it bold, italic, both, or by striking it through.

Bold text (strong emphasis)

To create bold text, also called strong emphasis, surround it with two asterisks or two underscores. Which one you use is a matter of taste. Seeing ** around words in an answer you pasted from ChatGPT or Claude? That’s Markdown bold, and here’s how to paste AI answers without the asterisks.

This is how you create **bold** text.
This is how you create __bold__ text.

Result: This is how you create bold text.

To make part of a word bold, use asterisks: un**believ**able works, but underscores inside a word are left alone, so snake__case__name stays as it is. That’s on purpose, so variable names don’t turn bold.

Italic text (emphasis)

To create italic text, surround it with single asterisks or single underscores:

This is how you create *italic* text.
This is how you create _italic_ text.

Result: This is how you create italic text.

Combine bold and italics

Use three asterisks or three underscores, or mix and match:

This is how you create ***bold italics*** text.
This is how you create ___bold italics___ text.
This is how you create **_bold italics_** text.

Result: This is how you create bold italics text.

Strikethrough

Surround text with two tildes to strike it through. This is a GFM extension, not part of core Markdown, but most modern tools support it:

This is how you create ~~strikethrough~~ text.

Result: This is how you create strikethrough text.

There’s no Markdown syntax for underlined text. See the FAQ at the end for the workaround.

Blockquotes

Start a line with > to quote it. Add a > to the empty lines between paragraphs to keep them in the same quote, and use >> to nest a quote inside a quote:

> Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
>
> You can use **other Markdown** inside a quote.
>
>> And this is a nested quote.

The result:

Markdown is intended to be as easy-to-read and easy-to-write as is feasible.

You can use other Markdown inside a quote.

And this is a nested quote.

Markdown lists

You can create ordered (numbered) lists and unordered (bulleted) lists. Both look natural in plain text, too. Leave a blank line between a paragraph and the list that follows it, to be safe.

Ordered lists

Put a number followed by a period at the start of each line:

1. Apples
2. Bananas
3. Peanut butter

The result:

1. Apples
2. Bananas
3. Peanut butter

After the first item, the numbers don’t matter. This list renders exactly the same as the one above:

1. Apples
1. Bananas
1. Peanut butter

The first number does count, though: a list that starts with 3. starts counting at 3. I usually number my lists properly since most lists are short, and it’s easier on the eyes in the source. For long lists that change often, all 1. saves you from renumbering.

Unordered lists

Start each line with a dash, an asterisk, or a plus sign. Pick one and stick with it within a list, because switching characters starts a new list.

- Apples
- Bananas
- Peanut butter

* Apples
* Bananas
* Peanut butter

Both lists result in:

• Apples
• Bananas
• Peanut butter

Nested lists

To nest a list, indent the child items so they line up with the text of the parent item. After - that’s 2 spaces; after 1. it’s 3 spaces. You can mix ordered and unordered lists:

1. Fruit
   - Apples
   - Bananas
2. Spreads
   - Peanut butter
     - Crunchy
     - Smooth

The result:

1. Fruit
   • Apples
   • Bananas
2. Spreads
   • Peanut butter
     • Crunchy
     • Smooth

The most common mistake: indenting only 2 spaces under a numbered item. In CommonMark and on GitHub, that ends the numbered list instead of nesting. Four spaces works under both - and 1., so if you want one rule to remember, use that.

Task lists (checklists)

Task lists, also called checklists or TODO lists, are a GFM extension. Add [ ] or [x] after the list marker. They work on GitHub, GitLab, and in many editors, but not everywhere (the WordPress editor, for example, doesn’t turn them into checkboxes):

- [x] Apples
- [ ] Bananas
- [ ] Peanut butter

The result:

• Apples
• Bananas
• Peanut butter

On GitHub, you can tick the boxes in issues and pull requests with a click, and the Markdown source updates itself. My article on Markdown checkboxes and task lists covers the spacing rules, checkboxes in tables, and where you can click them.

Links in Markdown

You can link to a website, a local file, or a heading in the same document. Put the link text in square brackets, directly followed by the URL in parentheses. My full guide to Markdown links covers heading anchors per platform, links to other files, new tabs, and troubleshooting.

Basic links

- An absolute link to [Markdown Land](https://markdown.land)
- A link with a title (shown on hover) to [Markdown Land](https://markdown.land "Markdown Land")
- A relative link to our [Markdown table guide](/markdown-table)
- A relative link to a file in a repo: [the code](../src/main.py)

The result (I left the last link unclickable, since that file doesn’t exist on this site):

• An absolute link to Markdown Land
• A link with a title (shown on hover) to Markdown Land
• A relative link to our Markdown table guide
• A relative link to a file in a repo: the code

Relative links are resolved from the location of the current file. They’re the way to go in a README.md or documentation folder because they keep working when someone forks or moves the repository.

Automatic links

Put a URL or email address in angle brackets to turn it into a link. That’s standard Markdown. GFM goes further and also links bare URLs that start with http://, https://, or www., but not plain domains like google.com.

<https://markdown.land> always becomes a link.
On GitHub, https://markdown.land and www.markdown.land do too.

Result: https://markdown.land always becomes a link. On GitHub, https://markdown.land and www.markdown.land do too.

Reference-style links

Reference-style links keep long URLs out of your sentences. You define the URL once, anywhere in the file (usually at the bottom), and refer to it by a label. Labels are case-insensitive, and the definitions themselves don’t show up in the output.

- Learn more on [this website about Markdown][markdown land].
- Learn Python with [the Python Land tutorial][1].
- Or reuse the link text as the label: [Python Land].

[Markdown Land]: https://markdown.land
[1]: https://python.land/python-tutorial
[Python Land]: https://python.land

The result:

• Learn more on this website about Markdown.
• Learn Python with the Python Land tutorial.
• Or reuse the link text as the label: Python Land.

Link to a heading (section links)

To link to a section in the same document, use # followed by the heading’s anchor id. On GitHub, the id is the heading text in lowercase, with spaces replaced by hyphens and most punctuation removed. A second heading with the same text gets -1 appended, a third -2, and so on.

## Getting Started

Jump to [Getting Started](#getting-started).
Link to a section in another file: [Install steps](docs/setup.md#install-steps)

Plain CommonMark doesn’t create heading ids at all, so this depends on your platform. GitHub, GitLab, most static site generators, and many editors add them automatically. On GitHub, you can also click the link icon next to any heading to get its URL. Did you know GitHub generates a table of contents for every README? Click the “Outline” button at the top of the file.

Images

An image looks like a link with an exclamation mark in front. The text in brackets is the alt text, which screen readers read out and browsers show if the image can’t load. The title in quotes is optional and shows on hover.

![The Markdown logo](images/markdown-logo.png "Markdown")

The result, with the image file being the Markdown logo:

The image path works just like a link: an absolute URL, or a path relative to the Markdown file. Reference-style works too: ![The Markdown logo][logo] with [logo]: images/markdown-logo.png elsewhere in the file.

Linked images

To make an image clickable, put the image syntax inside the brackets of a link. This is how most README badges work:

[![The Markdown logo](images/markdown-logo.png)](https://markdown.land)

The result (click it to go to the homepage):

Image size

Markdown has no syntax for image size. Use an HTML <img> tag with a width and/or height attribute instead. This works on GitHub, which keeps those attributes but strips style:

<img src="images/markdown-logo.png" alt="The Markdown logo" width="32">

Some tools have their own size syntax, like {width=50%} in Pandoc or ![alt|100](image.png) in Obsidian, but those don’t work elsewhere. For paths, captions, side-by-side images, GIFs, and troubleshooting, see my complete guide to Markdown images. Want to center an image? I wrote a separate article on how to center images, text, and tables in Markdown.

Inline code and code blocks

Code gets a monospaced font, and Markdown inside it is left alone. My article on Markdown code blocks goes into much more detail; here’s the short version.

Inline code

Surround code within a sentence with single backticks. If the code itself contains a backtick, surround it with double backticks and spaces:

Run `npm install` first.
Use `` `backticks` `` for inline code.

Result: Run npm install first. Use `backticks` for inline code.

Fenced code blocks

For multiple lines of code, put three backticks (or three tildes) on the line before and after the code. Add a language name after the opening backticks to get syntax highlighting on platforms that support it:

```python
def greet(name):
    print(f"Hello, {name}!")
```

The result is a code block like this one:

def greet(name):
    print(f"Hello, {name}!")

Fenced code blocks are part of CommonMark, so they work almost everywhere. You can also indent every line by four spaces to make a code block, but you can’t set a language that way. To show triple backticks inside a code block, fence it with four backticks or with ~~~.

Tables

Tables are a GFM extension, supported by GitHub, GitLab, and most editors. Separate columns with pipes | and put a row of dashes under the header row. Colons in that row set the alignment of a column: :--- left, :---: center, ---: right.

| Item         | Price | # In stock |
|--------------|:-----:|-----------:|
| Juicy Apples |  1.99 |        739 |
| Bananas      |  1.89 |          6 |

The result:

Item	Price	# In stock
Juicy Apples	1.99	739
Bananas	1.89	6

The pipes don’t need to line up; it just reads better. Head over to my Markdown table guide for all the details, like escaping pipes, line breaks in cells, and handy table generators.

Horizontal rules

Three or more dashes, asterisks, or underscores on a line of their own create a horizontal rule (a thematic break, <hr> in HTML):

Some text.

---

***

___

Each of the three lines results in:

---

Always leave a blank line above ---. Directly under a line of text, it turns that text into an H2 heading instead (see underlined headings).

Escaping characters

Sometimes you want a literal asterisk, hash, or underscore instead of formatting. Put a backslash \ in front of the character to escape it:

\*This is not italic\*
\# This is not a heading
1987\. A great year (and not a list item)

The result:

*This is not italic* # This is not a heading 1987. A great year (and not a list item)

These are the characters you’ll most often need to escape:

Character	Name
\	Backslash
`	Backtick
*	Asterisk
_	Underscore
{ }	Curly braces
[ ]	Square brackets
< >	Angle brackets
( )	Parentheses
#	Hash
+ -	Plus and minus (dash)
.	Period (after a number)
!	Exclamation mark
|	Pipe (in tables)
~	Tilde

In CommonMark and GFM, you can actually escape any ASCII punctuation character. A backslash before a letter or number stays a literal backslash. Inside inline code and code blocks, escaping isn’t needed (and doesn’t work), because everything is shown as-is.

Footnotes

Footnotes are a GFM extension, and tools like Pandoc and Obsidian support them too. Add [^label] in the text, and define the note anywhere in the file. The label can be a number or a word; the rendered notes are numbered automatically and always end up at the bottom.

Markdown was created by John Gruber in 2004.[^1]

[^1]: With a lot of help from Aaron Swartz.

The result:

Markdown was created by John Gruber in 2004.¹

---

1. With a lot of help from Aaron Swartz. ↩

GitHub alerts

Alerts (also called callouts or admonitions) are a GitHub-specific extension of the blockquote. Put one of five types on the first line of the quote: [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], or [!CAUTION].

> [!NOTE]
> Useful information that users should know, even when skimming.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

On GitHub, these render as colored boxes with an icon, roughly like this:

ⓘ Note

Useful information that users should know, even when skimming.

💡 Tip

Helpful advice for doing things better or more easily.

❗ Important

Key information users need to know to achieve their goal.

⚠ Warning

Urgent info that needs immediate attention to avoid problems.

⛔ Caution

Advises about risks or negative outcomes of certain actions.

Outside GitHub, most tools show an alert as a normal blockquote with the literal text [!NOTE] in it. Obsidian uses the same syntax for its callouts. Use alerts sparingly: one or two per document is plenty. They can’t be nested inside other elements, like lists. I tested every edge case, and compared them with Obsidian callouts and MkDocs admonitions, in my article on Markdown alerts. There’s more GitHub-specific syntax in my README.md guide.

Collapsible sections

Markdown has no syntax for collapsible content, but the HTML <details> and <summary> elements work on GitHub and in most other places that allow HTML. Leave a blank line after </summary>, or the Markdown inside won’t be rendered:

<details>
<summary>Click to see the installation steps</summary>

1. Download the installer
2. Run it with **admin rights**

</details>

The result (click it):

Click to see the installation steps

1. Download the installer
2. Run it with admin rights

Add the open attribute (<details open>) to have the section expanded by default.

Comments in Markdown

Markdown has no official comment syntax, but there are two reliable tricks. The first is an HTML comment. It’s hidden on the rendered page, but most renderers copy it into the HTML source, where anyone who views the source can read it. GitHub removes it from the page, but anyone can still read it in the raw file:

<!-- TODO: add a screenshot here -->

<!--
Comments can span
multiple lines, too.
-->

The second trick abuses a reference-style link definition that nothing links to. It doesn’t appear in the output at all, not even in the HTML source:

[//]: # (This comment is completely invisible)

Put a blank line before and after it, and keep it on a single line. Both tricks render as nothing, so there’s no result to show here. My article on comments in Markdown compares them per platform.

HTML in Markdown

When Markdown has no syntax for something, you can usually write HTML directly in your Markdown file. A few useful examples:

Press <kbd>Ctrl</kbd> + <kbd>C</kbd> to copy.
H<sub>2</sub>O and E = mc<sup>2</sup>
This is <ins>underlined</ins> text.

Result: Press Ctrl + C to copy. H₂O and E = mc² This is underlined text.

There are a few things to keep in mind:

• Markdown isn’t processed inside HTML block elements like <div>, unless you leave blank lines around the Markdown, like in the <details> example above.
• Platforms filter HTML for security. GitHub removes <script>, <style>, and style="" attributes, but keeps attributes like align, width, and height. That’s why centering content in Markdown on GitHub needs align="center".
• Some tools don’t allow HTML at all. In that case, the tags show up as plain text or disappear.

Emojis

Let me start with the disclaimer: use emojis sparingly to not annoy your readers or look like a child 😅

There are two ways to add emojis to your Markdown file:

1. By copying the Unicode character and pasting it into your file
2. By using an emoji shortcode

Copy and paste emojis into Markdown

The quickest method, and the one that works everywhere, is to copy and paste the emoji. Many sites help you find and copy emojis. Here’s one, and here’s another one. Select the emoji you like, hit Ctrl+C, and paste it into your Markdown file with Ctrl+V (Cmd+C and Cmd+V on a Mac). You can also use your operating system’s emoji picker: Win+. on Windows, Ctrl+Cmd+Space on a Mac.

Using shortcodes

An emoji shortcode is a word surrounded by colons, like these:

:smile: :laughing: :wink: :rocket:

Result on GitHub: 😄 😆 😉 🚀

Shortcodes aren’t part of CommonMark or GFM. GitHub, GitLab, Slack, and Discord support them, but many other tools show the text :smile: as-is, and the list of available words differs per platform. Here’s a list of shortcodes that work on GitHub. I prefer pasting the real emoji, because it’s more readable in the source, too.

Markdown flavors

John Gruber’s original Markdown from 2004 left many details open, so every tool filled in the gaps differently. Today, two specifications matter most:

• CommonMark is the precise, standardized version of core Markdown: headings, emphasis, lists, links, images, code, blockquotes, horizontal rules, and HTML.
• GitHub Flavored Markdown (GFM) is CommonMark plus tables, task lists, strikethrough, and automatic links for bare URLs. GitHub also renders footnotes, alerts, emoji shortcodes, diagrams, and math on top of that.

If something from this cheat sheet doesn’t work in your tool, the flavor is usually the reason. Check the Notes column in the quick reference table at the top.

GitHub extras: diagrams and math

On GitHub, a code block with the language mermaid is rendered as a diagram (flowcharts, sequence diagrams, and more):

```mermaid
flowchart LR
    A[Write Markdown] --> B[Commit] --> C[GitHub renders it]
```

GitHub also renders math written in LaTeX syntax. Use $...$ for inline math and $$...$$ (or a math code block) for a formula on its own line:

The area of a circle is $\pi r^2$.

$$
E = mc^2
$$

GitHub’s documentation has all the details on diagrams and math. For everything else GitHub-specific, like profile READMEs and light/dark mode images, see my README.md guide.

FAQ

How do I add a new line in Markdown without starting a new paragraph?

End the line with a backslash \ or with two spaces, or use <br>. A single Enter is ignored in most Markdown files, and a blank line starts a new paragraph. See paragraphs and line breaks, or my full article on Markdown line breaks.

How do I underline text in Markdown?

There’s no Markdown syntax for underlining, because underlined text is easily mistaken for a link. If you really need it, use HTML: <ins>text</ins> works on GitHub, and <u>text</u> works in most other places that allow HTML.

Can I change the text color or font size in Markdown?

Not with Markdown itself. Where HTML with style attributes is allowed, you can use something like <span style="color:red">, but GitHub strips style, so it won’t work there. For emphasis, stick to bold, italics, or a GitHub alert.

Why does my Markdown look different on GitHub than in my editor?

Different tools support different Markdown flavors. Tables, task lists, footnotes, alerts, and emoji shortcodes are extensions that not every tool supports. GitHub also filters HTML and treats single line breaks differently in comments than in files.

How do I center text or an image in Markdown?

Markdown can’t center anything by itself, so you need HTML. On GitHub, wrap the content in <p align="center"> or <div align="center">. My article on centering in Markdown covers all the options per platform.

What file extension do Markdown files use?

Use .md. The longer .markdown also works, but .md is by far the most common, as in README.md. For the complete, official rules behind this cheat sheet, see the CommonMark spec and GitHub’s basic writing and formatting syntax.