Markdown syntax, quick reference

Common markdown syntax
Element	Markdown
Heading	`# H1 ## H2 ### H3`
Bold	`bold text`
Italic	`italic text`
Strikethrough	`~~struck text~~`
Blockquote	`> quoted text`
Ordered list	`1. First item`
Unordered list	`- First item`
Task list	`- [x] Done`
Inline code	`code`
Code block	```js … ```
Link	`[title](https://example.com)`

Element	Markdown
Image	`![alt text](image.png)`
Table	`\| A \| B \| \|---\|---\|`
Footnote	`Text[^1] [^1]: Note`
Horizontal rule	`---`
Line break	`end a line with \`
Alert	`> [!NOTE]`
Math	$E = mc^2$
Diagram	```mermaid
Emoji	`:rocket:`
Escape	`\not italic\`
Comment	`<!-- hidden -->`

CommonMark: Core markdown — works almost everywhere markdown is rendered.
GFM: GitHub Flavored Markdown — supported by GitHub, GitLab, Reddit, VS Code and many other tools.
GitHub: A GitHub extension, also supported by RenderMD and some other tools.
Extended: Not part of any spec, but supported by GitHub, GitLab, Obsidian, RenderMD and others.

The basics

CommonMark: the core syntax that works in nearly every markdown renderer.

§01

Headings

CommonMark

Start a line with one to six # characters and a space. One # is the page title; use ## and below for sections.

Markdown· Click to edit

Result

Heading 1

Q: What’s the difference between CommonMark and GitHub Flavored Markdown?

CommonMark is the formal specification of core markdown — headings, emphasis, lists, links, images, code and quotes. GitHub Flavored Markdown (GFM) is a superset that adds tables, task lists, strikethrough, autolinks and footnotes. Anything written in CommonMark also works in GFM.

Q: How do I add a line break without starting a new paragraph?

End the line with a backslash (\) or two spaces. A blank line starts a new paragraph, and a single newline on its own is treated as a space.

Q: How do I make a table in markdown?

Separate columns with | and add a line of dashes under the header row: | Name | Role | then | --- | --- |. Put colons in the dash row to align columns: :--- left, :---: center, ---: right.

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

Alternative syntax

Markdown· Click to edit

Result

Heading 1

Heading 2

§02

Paragraphs & line breaks

CommonMark

Separate paragraphs with a blank line. A single newline is treated as a space. To force a line break, end the line with a backslash (or two spaces).

Markdown· Click to edit

Result

This is the first paragraph. This line joins the one above.

This is a second paragraph.

Hard line breaks

Markdown· Click to edit

Result

Roses are red,
violets are blue,
markdown is simple and so are you.

§03

Bold & italic

CommonMark

Wrap text in one asterisk for italic, two for bold, and three for both. Underscores work too.

Markdown· Click to edit

Result

Italic or italic

Bold or bold

Bold and italic

A bold and italic mix.

§04

Blockquotes

CommonMark

Start a line with > to quote it. Quotes can span paragraphs, nest, and contain any other markdown.

Markdown· Click to edit

Result

Simplicity is prerequisite for reliability.

— Edsger W. Dijkstra

Nested, with formatting

Markdown· Click to edit

Result

Note: quotes can hold other blocks.

Lists

and emphasis

Even another quote.

§05

Lists

CommonMark

Use -, * or + for bullets and numbers followed by . for ordered lists. Indent items to nest them under the previous one.

Unordered

Markdown· Click to edit

Result

Coffee
Tea
- Green
- Black
Water

Ordered

Markdown· Click to edit

Result

Preheat the oven
Mix the batter
Bake for 25 minutes

Starting number

Markdown· Click to edit

Result

Lists can start at any number
and keep counting from there

Paragraphs inside items

Markdown· Click to edit

Result

First step

Indent follow-up paragraphs to match the text so they stay inside the item.
Second step

§06

Code

CommonMark

Use single backticks for inline code and triple-backtick “fences” for blocks. Name the language after the opening fence to get syntax highlighting.

Inline

Markdown· Click to edit

Result

Run npm install and open index.html.

Fenced, with a language

Markdown· Click to edit

Result

function greet(name) {
  return `Hello, ${name}!`
}

With a file title

Markdown· Click to edit

Result

tsgreet.ts

export const greet = (name: string) => `Hello, ${name}!`

Diffs

Markdown· Click to edit

Result

diff

- const theme = "default"
+ const theme = "editorial"

§07

Links

CommonMark

Put the link text in square brackets and the URL in parentheses. Add an optional title in quotes, or use reference-style links to keep paragraphs readable.

Inline

Markdown· Click to edit

Result

RenderMD is free.

Reference style

Markdown· Click to edit

Result

Read the CommonMark spec and the GFM spec.

Autolinks

Markdown· Click to edit

Result

https://www.render-md.com

Bare URLs work in GFM: https://commonmark.org

So do emails: hello@example.com

Section links

Markdown· Click to edit

Result

Jump back to Headings.

§08

Images

CommonMark

Images are links with a leading !. The text in brackets becomes the alt text — describe the image for people who can’t see it.

Linked images & badges

Markdown· Click to edit

Result

§09

Horizontal rules

CommonMark

Three or more dashes, asterisks or underscores on a line of their own make a thematic break.

Markdown· Click to edit

Result

Above the break.

Below the break.

§10

Escaping characters

CommonMark

Put a backslash before any markdown character to show it literally.

Markdown· Click to edit

Result

*Not italic* and # not a heading.

1986. A great year — not a list.

Use `backticks` without code.

II.

GitHub Flavored Markdown

GitHub’s additions to CommonMark, also supported by GitLab, VS Code, Obsidian and Reddit.

§11

Tables

GFM

Separate columns with pipes and put a row of dashes under the header. Colons in that row align the column left, center or right.

Markdown· Click to edit

Result

Planet	Moons	Day length
Mercury	0	4,222 h
Earth	1	24 h
Mars	2	24.7 h

Formatting inside cells

Markdown· Click to edit

Result

Syntax	Result
`bold`	bold
`a \| b`	a \| b
Line break	via `<br>`

§12

Task lists

GFM

Add [ ] or [x] after a list bullet to make a checklist.

Markdown· Click to edit

Result

Write the draft
Add a diagram
Share the link
- Nested tasks work too

§13

Strikethrough

GFM

Wrap text in double tildes to strike it through.

Markdown· Click to edit

Result

The meeting is ~~Tuesday~~ Wednesday.

§14

Footnotes

GFM

Add a reference like [^1] in the text and define it anywhere below. Footnotes are numbered automatically and collected at the end.

Markdown· Click to edit

Result

Markdown was created in 2004.¹ It was standardised as CommonMark in 2014.²

By John Gruber, with Aaron Swartz. ↩
See https://commonmark.org. ↩

§15

Alerts

GitHub

A blockquote that starts with [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] or [!CAUTION] becomes a callout.

Markdown· Click to edit

Result

Note

Useful information worth a glance.

Markdown· Click to edit

Result

Tip

A better way to do something.

Markdown· Click to edit

Result

Important

Key information users need to know.

Markdown· Click to edit

Result

Warning

Urgent info that needs immediate attention.

Markdown· Click to edit

Result

Caution

Advises about risks or negative outcomes.

III.

Beyond the spec

Not part of any markdown standard, but supported by GitHub, GitLab and Obsidian.

§16

Math

Extended

Write LaTeX between single dollar signs for inline math and double dollar signs for display equations. RenderMD typesets it with KaTeX.

Inline

Markdown· Click to edit

Result

Pythagoras: $a^2 + b^2 = c^2$ , and Euler: $e^{i\pi} + 1 = 0$ .

Display

Markdown· Click to edit

Result

\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}

Multi-line

Markdown· Click to edit

Result

\begin{aligned} \nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\ \nabla \cdot \mathbf{B} &= 0 \end{aligned}

Math code block

Markdown· Click to edit

Result

f(x) = \int_{-\infty}^{\infty} \hat f(\xi)\, e^{2 \pi i \xi x} \,d\xi

§17

Diagrams

Extended

A code block with the language mermaid becomes a diagram: flowcharts, sequence diagrams, Gantt charts, class and state diagrams, pie charts, timelines and more.

Flowchart

Markdown· Click to edit

Result

Mermaid

Sequence diagram

Markdown· Click to edit

Result

Mermaid

Pie chart

Markdown· Click to edit

Result

Mermaid

§18

Emoji

Extended

Type an emoji shortcode between colons, or paste the emoji itself.

Markdown· Click to edit

Result

Ship it 🚀 Tests pass ✅ Time to celebrate 🎉

§19

HTML

Extended

Most renderers allow a safe subset of HTML for things markdown can’t do. Leave a blank line between HTML and markdown so the markdown inside is still parsed.

Collapsible sections

Markdown· Click to edit

Result

Show the answer

Forty-two. Markdown still works in here.

Keyboard keys

Markdown· Click to edit

Result

Press Ctrl + C to copy, ⌘ + K for commands.

Sub, superscript & highlight

Markdown· Click to edit

Result

H₂O, E = mc², and a highlighted phrase.

§20

Comments

CommonMark

HTML comments don’t appear on the rendered page. Use them for notes to yourself or other authors.

Markdown· Click to edit

Result

Visible text.

More visible text.

§21

Frontmatter

Extended

A YAML block between --- lines at the very top of a file holds metadata such as a title, date or tags. Static site generators like Jekyll, Hugo and Astro read it.

Markdown· Click to edit

Result

What’s new

Frequently asked

What is markdown?

Markdown is a lightweight way to format plain text. You write **bold** or # Heading and a renderer turns it into formatted text. John Gruber created it in 2004.

What’s the difference between CommonMark and GitHub Flavored Markdown?

CommonMark is the formal specification of core markdown — headings, emphasis, lists, links, images, code and quotes. GitHub Flavored Markdown (GFM) is a superset that adds tables, task lists, strikethrough, autolinks and footnotes. Anything written in CommonMark also works in GFM.

How do I add a line break without starting a new paragraph?

End the line with a backslash (\) or two spaces. A blank line starts a new paragraph, and a single newline on its own is treated as a space.

How do I make a table in markdown?

Separate columns with | and add a line of dashes under the header row: | Name | Role | then | --- | --- |. Put colons in the dash row to align columns: :--- left, :---: center, ---: right.

How do I write math equations in markdown?

Use LaTeX between dollar signs: $E = mc^2$ for inline math and $$ … $$ on their own lines for display equations. GitHub, GitLab, Obsidian and RenderMD all support this syntax.

Can I use HTML in markdown?

Yes. Most renderers allow a safe subset of HTML for things markdown can’t express, like <details> for collapsible sections, <kbd> for keys and <img width="…"> for sized images. Scripts and event handlers are always removed.

How can I preview a markdown file?

Paste or drop it into RenderMD. It renders in your browser, including tables, math and diagrams, and the file is never uploaded. You can also open a URL or a GitHub repository directly.