Markdown syntax: a working guide with the HTML it produces
Markdown is a plain-text format that turns simple punctuation into formatted HTML. A README, a forum post or a note app may all accept it, and the core rules are the same everywhere.
The core syntax and its output
| You type | HTML result |
|---|---|
# Title | <h1>Title</h1> (use ## to ###### for levels 2 to 6) |
*word* or _word_ | <em>word</em> |
**word** | <strong>word</strong> |
`code` | <code>code</code> |
[text](/page.html) | a link with that text and address |
 | an image with alt text |
> quoted | <blockquote> |
- item or 1. item | an unordered or ordered list |
--- on its own line | <hr> |
Blank lines are the real syntax
Most surprises in Markdown come from line breaks, not symbols. Learn these three rules and most rendering problems disappear:
- A blank line starts a new paragraph. Two lines with no blank line between them join into one paragraph.
- A single line break is not a line break. To force one inside a paragraph, end the line with two spaces or a backslash. Some platforms, such as many chat and comment boxes, treat every line break as a real break; most documentation tools do not.
- Put a blank line before a list, heading or code block when it follows a paragraph. Some renderers need it to recognise the block.
Example. This source renders as one paragraph, “Milk Eggs Bread”:
Milk
Eggs
Bread
Write it as a list instead: - Milk, - Eggs, - Bread on three lines.
Code blocks
Wrap a block of code in three backticks on their own lines. Most renderers accept a language name after the opening fence and use it for syntax colouring:
```js
const total = items.reduce((sum, x) => sum + x.price, 0);
```
Inside a fence, Markdown does nothing: asterisks and underscores stay as typed. To show a backtick inside inline code, wrap it with double backticks: `` a ` b ``.
Lists that nest correctly
Indent a nested item so it lines up with the text of its parent item, not with the bullet. For - that is two spaces; for 1. it is three. Numbered lists only use the first number, so 1., 1., 1. renders as 1, 2, 3, which makes reordering easy.
Tables and other extensions
The original Markdown had no tables. CommonMark is a precise specification of the core language, and GitHub Flavored Markdown (GFM) adds tables, task lists and strikethrough on top of it:
| Size | Width |
|------|------:|
| S | 40cm |
| M | 44cm |
- [x] Draft written
- [ ] Links checked
~~old price~~
The colon in ------: aligns that column to the right. Extensions vary between tools, so check what your platform supports before relying on them.
Escaping symbols
Put a backslash before a character to show it literally. \*not italic\* shows the asterisks. This matters for prices and maths: 2*3*4 can turn the 3 into italics, so write 2\*3\*4 or use code formatting.
How a Markdown editor works
A live editor runs a parser on every change. The parser reads the text into blocks, then inline elements, then outputs HTML for a preview pane. Because Markdown also allows raw HTML, an editor that shows other people’s Markdown must sanitise the output, removing scripts and event attributes, or it opens a cross-site scripting hole.
Common mistakes
- No space after
#:#Titleis plain text in CommonMark. - Spaces inside emphasis markers:
** bold **does not render as bold. - Underscores inside words such as
file_name_here, which some older renderers turn into italics.
Questions
Which Markdown flavour should I write?
Write CommonMark for the core features and add GFM tables or task lists only where your platform supports them. That keeps documents portable.
Can I mix HTML into Markdown?
Usually yes, for example a <details> block. Many sites strip some tags for safety, so test on the platform you publish to.