Markdown Cheatsheet

About the Markdown Cheatsheet

What is the difference between CommonMark and GitHub Flavored Markdown?

CommonMark is the unambiguous specification of Markdown published in 2014 that resolves the dozens of edge cases left vague in John Gruber's original 2004 description. GitHub Flavored Markdown (GFM) is a strict superset of CommonMark - everything CommonMark supports is supported in GFM identically, plus the GFM specification adds tables, task lists, strikethrough, autolinks, and a few extra rules. The newer GitHub-specific features such as callout blocks (> [!NOTE]), collapsible details, syntax-highlighted fenced code, and emoji shortcodes are not strictly part of GFM but are rendered by GitHub anyway. This cheatsheet labels them as 'GFM extensions' for convenience, but note that not every Markdown engine will render them; for portable documents stick to plain CommonMark.

Why does my list not render correctly?

The single most common Markdown rendering issue is missing the blank line that separates a list from the surrounding paragraph. The CommonMark specification requires a blank line before any list - otherwise the first item gets glued to the preceding text as a single paragraph. The second most common issue is nesting indentation: each level should be indented by exactly the width of the marker plus one space (typically two spaces for unordered lists, three or four for ordered lists). If a nested item refuses to indent, double-check that the parent line ends without a trailing space and that you used spaces rather than tabs. Finally, some legacy parsers do not accept numbers other than 1 as the first ordered-list item; CommonMark accepts any number but renders them sequentially.

How do I escape Markdown special characters?

Place a backslash before any character that Markdown would otherwise interpret: \*not italic\*, \#not-heading, \[not-a-link\]. The escapable characters are: \ ` * _ { } [ ] ( ) # + - . ! | > and ~. Outside those, a backslash is left as-is. The trickier case is when you want literal backticks inside inline code: surround your code with a longer run of backticks, so ``code with ` inside`` becomes <code>code with ` inside</code>. For backslashes themselves, double them: \\. Most editors with a Markdown preview will show you immediately whether the escape worked, so use a live preview when in doubt.

Are GitHub callout blocks portable to other tools?

The > [!NOTE] / [!TIP] / [!WARNING] / [!IMPORTANT] / [!CAUTION] callout syntax was introduced by GitHub in late 2023 and adopted shortly after by GitLab. Renderers that have not implemented it (most static-site generators, Notion, and older Markdown editors) treat the block as an ordinary blockquote, which is graceful - the warning still reads correctly, just without the coloured banner. If you publish your docs to a platform like MkDocs, Hugo, or Jekyll, prefer the platform's native admonition syntax (e.g. !!! note ... in MkDocs Material). For maximum portability, write callouts as plain bold-prefixed blockquotes: > **Note:** ... which renders sensibly everywhere.

How do I write math equations in Markdown?

Inline math goes between single dollar signs: $E = mc^2$. Block math goes between double dollar signs on their own lines, like $$\int_0^1 x^2 dx$$. The actual rendering depends on the Markdown engine: GitHub, GitLab, Obsidian, Notion, and Quarto all natively support TeX/LaTeX math via KaTeX or MathJax; classic CommonMark does not. If you publish through a static-site generator, install a math plugin (rehype-katex for unified, mkdocs-material with arithmatex for MkDocs, hugo-katex for Hugo). Escape isolated dollar signs that should appear as currency with a backslash: \$5 - otherwise the engine may try to start math mode and produce strange output.

Why does this cheatsheet load so much faster than other docs sites?

Three reasons. First, every card is server-rendered into static HTML; there is no client-side Markdown parser to wait for, no Mermaid bundles, no syntax highlighter JavaScript - the bytes you see on screen are the bytes the server sent. Second, the search uses a vanilla querySelectorAll filter over a few dozen cards, so even on a low-end phone every keystroke updates the DOM in under a millisecond. Third, the page is cached aggressively by the WuTools infrastructure: HTML is cached for ten days, the small JS for the filter is cached for a year, and so are the SVG icons. Once a returning visitor has the page in cache, the cheatsheet appears in roughly the same time it takes the browser to draw a frame.