Markdown syntax reference
Markdown is small enough to learn in an afternoon and powerful enough to write everything from READMEs to books. This cheat sheet collects the syntax you will actually use, with copy-paste examples for every element. Test any of them instantly in a Markdown viewer.
The examples distinguish basic Markdown from extensions commonly supported by GitHub and other renderers. Features such as footnotes and raw HTML vary by application; check the destination when a document does not render as expected.
Headings
# H1 — document title
## H2 — section
### H3 — subsection
#### H4
##### H5
###### H6
Use exactly one H1 per document as the title, and do not skip levels — a clean heading hierarchy powers navigation, tables of contents, and accessibility.
Paragraphs and line breaks
A blank line starts a new paragraph.
To break a line without a new paragraph, end the line
with two trailing spaces.
Most of the time, paragraphs are all you need. Reserve forced line breaks for poetry and addresses.
A single newline in source is usually a soft break and may display as a space. To force a line break in CommonMark and GFM, end the line with two spaces or a backslash:
First line\
Second line
This starts a separate paragraph.
GitHub issue comments and repository Markdown files may handle soft breaks differently. Raw <br> is another renderer-dependent option; MD Opener's main viewer deliberately omits raw HTML.
Emphasis
*italic* _also italic_
**bold** __also bold__
***bold italic***
~~strikethrough~~
`inline code`
Strikethrough (~~) is a GFM extension. Inline code disables Markdown inside it, so you can show raw syntax safely.
Links and images
[link text](https://example.com)
[link with title](https://example.com "hover title")
<https://autolink.example.com>
GFM also autolinks bare URLs without angle brackets. Always write meaningful link text — "read the docs" beats "click here" for both readers and search engines.
Lists
- Unordered item
- Another item
- Nested item
- Nested item
1. Ordered item
2. Ordered item
1. Nested ordered
2. Nested ordered
Use - or * for unordered lists, and numbers for ordered ones. Keep nesting to two levels for readability.
Task lists
- [x] Done task
- [ ] Open task
- [ ] Another open task
A GFM feature that turns bullets into checkboxes — perfect for READMEs, issues, and step trackers.
Tables
| Syntax | Description |
| --- | --- |
| Header | Title |
| Paragraph | Text |
| Left | Center | Right |
| :--- | :---: | ---: |
| a | b | c |
The colon placement in the separator row controls column alignment. Keep tables to a clean grid — merged and nested cells are not supported.
Code blocks
Fenced code blocks use three backticks. Add a language tag for syntax highlighting:
```js
function greet(name) {
return `Hello, ${name}!`
}
```
Indenting a block by four spaces also creates a code block, but fences are clearer and support a language tag.
Blockquotes
> This is a quote.
> It can span multiple lines.
>
> Even with multiple paragraphs.
Use blockquotes to highlight notes, warnings, or quoted material.
Horizontal rules
---
or
***
Three or more hyphens, asterisks, or underscores on a line create a horizontal divider. Use them sparingly to separate major sections.
Escaping characters
Use \*literal asterisks\* or a \# literal hash.
A backslash escapes Markdown special characters when you need them to appear literally.
Footnotes
GitHub supports footnotes, as do many extended Markdown renderers. They are not part of the formal GFM specification:
Markdown was created to be easy to write and read.[^1]
[^1]: John Gruber published the original syntax in 2004.
The footnote marker appears inline, and the footnote content renders at the bottom of the document with a back-link. Use footnotes for citations, clarifications, and tangential notes that do not belong in the flow of a paragraph.
Definition lists and HTML fallback
For elements Markdown does not cover natively — such as definition lists, collapsible details, or specific styling — GFM lets you drop in raw HTML:
<details>
<summary>Click to expand</summary>
Hidden content lives here, including **formatted** Markdown.
</details>
Raw HTML support depends on the renderer. MD Opener's main viewer omits raw HTML, while its separate Markdown editor sanitizes allowed HTML. A <details> block therefore will not behave identically in every preview or exported format. Use ordinary headings and lists when portability matters.
Common mistakes to avoid
A handful of errors account for most broken Markdown:
- Missing blank lines around block elements. Tables, lists, and code blocks need a blank line above and below to render as blocks rather than running into paragraphs.
- Inconsistent list indentation. Items at the same nesting level must use the same indentation, or the list breaks into separate lists.
- Unescaped special characters. A stray
*or_can accidentally start emphasis. Escape with a backslash when you mean it literally. - Broken links. A missing parenthesis or space inside
[]()silently breaks a link. Preview before publishing. - Skipped heading levels. Jumping from H2 to H4 breaks the document outline. Go in order.
Putting it together
A typical document combines several elements. Here is a realistic README skeleton:
# Project Name
Short description of what the project does.
## Features
- [x] Fast rendering
- [x] Local processing
- [ ] Plugin system
## Installation
1. Clone the repo
2. Run `npm install`
3. Start the server
## Configuration
| Option | Default | Description |
| --- | --- | --- |
| `port` | `3000` | Server port |
| `debug` | `false` | Verbose logs |
> Restart the server after changing configuration.
That single file uses a heading, a task list, an ordered list, inline code, a table, and a blockquote — most of the syntax you will ever need.
Test it live
Reading a cheat sheet is one thing; seeing it render is another. Open the Markdown viewer, paste any block from this page, and watch it come to life. When you are ready to turn that Markdown into another format, jump to Markdown to HTML, Markdown to PDF, or Markdown to Word.
Table of contents
A Markdown table of contents is a list of links to headings. It is different from a data table. For GitHub-style anchors, a heading such as ## Installation notes is linked with [Installation notes](#installation-notes). Repeated headings need unique suffixes; punctuation and Unicode also affect the final ID.
Use the Markdown table of contents generator to build this list from an existing document. It excludes code blocks and preserves anchors when you filter heading levels. The Markdown table generator handles data tables instead, with an editable grid and column alignment.
Syntax sources
Consult CommonMark for basic blocks and inline syntax, the GFM specification for tables and task lists, and GitHub's formatting documentation for platform-specific behavior.