Markdown Cheat Sheet for Developers

Markdown is the default writing format for READMEs, documentation, changelogs, issue trackers and many blogs. The core syntax fits on one page.

Basics

Lists

- Bullet item
- Another item

1. First
2. Second
3. Third

Leave a blank line before a list, and indent nested items consistently (two or four spaces).

Code blocks

Fence code with three backticks on their own lines before and after, and name the language after the opening fence for syntax highlighting:

const total = items.reduce((s, i) => s + i.price, 0);

To show a fenced block inside a fenced block (as in documentation about Markdown), make the outer fence longer — four backticks instead of three.

Tables

| Plan | Price | Seats |
|---|---|---|
| Starter | 99 | 2 |
| Growth | 249 | 10 |

Colons in the divider row set alignment: :--- left, :---: centre, ---: right. Tables are a GitHub-flavoured extension, not part of original Markdown.

Common gotchas

1. Line breaks. A single newline inside a paragraph usually doesn't break the line. End the line with two spaces or a backslash, or leave a blank line for a new paragraph.
2. Blank lines around blocks. Lists, code fences, headings and tables need a blank line before them in many renderers.
3. Escaping. Use a backslash to show literal symbols: \* \_ \# \[.
4. Underscores in words (snake_case) can trigger emphasis in some renderers. Wrap identifiers in backticks.
5. Raw HTML is allowed in some renderers and stripped or escaped in others, for security.
6. Relative links and images break when the file is rendered somewhere else. Test where it will be published.
7. Heading IDs (anchors) are generated differently between platforms; don't depend on them across systems.

Flavours

• CommonMark is the standardised core.
• GitHub Flavored Markdown (GFM) adds tables, task lists, strikethrough and autolinks.
• Platforms such as docs generators and blog engines add their own extensions (admonitions, footnotes, front matter). Check yours.

Writing tips for docs

• Lead with what the reader can do, then how.
• One idea per paragraph; short sentences.
• Use headings so people can scan, and a table when comparing.
• Put commands in code blocks, never in screenshots.

Preview before you publish

Paste your draft into the free Markdown Previewer for a live side-by-side preview with tables and code blocks, then copy the HTML or download .md or .html. Raw HTML in the input is escaped and javascript: links are neutralised. Compare revisions with the Text Diff Checker, and check length for titles and descriptions with the Word & Character Counter.

Building documentation sites and content platforms

If you're planning a docs site, blog or knowledge base with search, versioning and a proper publishing workflow, see website development with Pyalm and Next.js and web development notes, or get in touch.