Markdown syntax
All of everyday Markdown on one sheet — headings, emphasis, lists, links, images, code and tables — each with what it renders as.
Last updated
Headings & emphasis
| You type | You get |
|---|---|
| # Title / ## Section | Heading level 1 / level 2 — one # per level, up to six. |
| **bold** | Bold text. |
| *italic* | Italic text. |
| ~~struck~~ | Strikethrough (GitHub-flavoured). |
| `code` | Inline code in a monospace chip. |
Lists & quotes
| You type | You get |
|---|---|
| - item | A bulleted list; indent two spaces to nest. |
| 1. item | A numbered list — the numbers self-correct, so 1. everywhere works. |
| - [ ] task / - [x] done | Checkboxes (GitHub-flavoured task list). |
| > quoted line | A blockquote; stack the > for nesting. |
Links & images
| You type | You get |
|---|---|
| [text](https://url) | A link with custom text. |
|  | An image — the leading ! is the whole difference from a link. |
| <https://url> | A bare auto-link, shown as-is. |
Code blocks
| You type | You get |
|---|---|
| ```js … ``` | A fenced code block; the word after the fence sets syntax highlighting. |
| four spaces | The old-style indented code block — fences are clearer, prefer them. |
Tables & extras
| You type | You get |
|---|---|
| | a | b | with | --- | --- | | A table: header row, then a divider row of dashes, then data rows. |
| | :--- | :---: | ---: | | Column alignment in the divider — left, centre, right. |
| --- | A horizontal rule, on its own line with blank lines around it. |
| Two trailing spaces | A line break WITHIN a paragraph (or end the line with a backslash). |
Worth remembering
- →Blank lines matter more than anything else: most "broken" Markdown is a missing empty line before a list, table or fence.
- →Preview any of this live in the Markdown Preview tool — type on the left, rendered result on the right.
Questions
Why does my line break disappear?
A single newline is not a break in most Markdown — it renders as a space. Use two trailing spaces, a backslash, or a blank line for a new paragraph, depending on which flavour you are writing for.
Which flavour am I actually writing?
Almost certainly not the original. GitHub Flavoured Markdown adds tables, task lists, strikethrough and autolinks, and it is the de facto standard — but a static site generator may support a different set.
How do I show a code block inside a code block?
Use more backticks on the outer fence than the inner one — four outside, three inside. The fence length is what determines where the block ends.
Why did my underscore turn something italic?
Because it is emphasis syntax, so snake_case_names can render unexpectedly mid-sentence. Escape the underscores with a backslash, or wrap the term in backticks, which is usually what you meant anyway.
Is HTML allowed inside Markdown?
Usually yes, and many renderers strip it for safety when the input is untrusted. Relying on it makes a document non-portable, so prefer Markdown syntax where one exists.
How do I get a table to align the way I want?
Colons in the separator row control it — a colon on the left aligns left, on the right aligns right, and one at each end centres the column. The pipes do not need to line up in the source, which is why raw tables look ragged and render evenly.
Why does my numbered list restart at one?
A blank line or an inconsistent indent between items breaks the list into two. Markdown also renumbers automatically, so a list written entirely with 1. renders in the right order — which is worth using, since it survives reordering the items.