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.

How do I make a table in Markdown and align the columns?

Tables use pipes to separate columns and a divider row of dashes to separate the header from the body: | Name | Score | on the first line, |------|-------| on the second, then one | value | value | row per record. The dashes only need to be present, not aligned to the text. To control column alignment, add a colon to the divider row: |:---| is left, |:--:| is center, and |---:| is right. So a row like |:--|:-:|--:| gives left, center, right columns. You do not need outer pipes, but they make the source easier to read and copy. If a cell must contain a literal pipe character, escape it with a backslash as \| so the parser does not treat it as a column break - this is the most common gotcha when putting code or regex inside a table cell. Tables are a GFM extension, so GitHub, GitLab, and Obsidian render them but strict CommonMark does not.

How do I add a line break in Markdown?

Markdown has three ways to force a single line break inside a paragraph. The classic method is to end the line with two trailing spaces, then press Enter - the trouble is that trailing whitespace is invisible and many editors strip it automatically. The more reliable GFM method is a trailing backslash at the end of the line, which is visible in the source and survives whitespace trimming. The third way is the raw HTML <br> tag, which works in essentially every renderer including strict CommonMark. To start a brand-new paragraph instead of a soft break, simply leave a completely blank line between the two blocks of text; that is the most portable separator of all and what you want most of the time.

Which Markdown features work on GitHub vs GitLab vs CommonMark?

It depends on the construct, which is exactly what the compatibility badges on each card show. Bold, italic, headings, links, images, blockquotes, lists, and fenced code are core CommonMark and render identically everywhere. Tables, task lists, strikethrough, and bare-URL autolinks are GFM extensions: GitHub, GitLab, and Obsidian support them, but strict CommonMark does not. Footnotes and TeX/LaTeX math render on GitHub, GitLab, and Obsidian but not in plain CommonMark. GitHub callouts (> [!NOTE]) work on GitHub, GitLab, and Obsidian (Obsidian has native callouts) yet degrade to a plain blockquote elsewhere. @mentions and #issue references are GitHub-specific. Definition lists (term / : definition) are a Markdown Extra / pandoc feature and render on none of the four. For documents that must survive any pipeline, click the "Portable only" toggle to filter the sheet down to the CommonMark-safe subset.

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.