The Markdown Cheatsheet Every Developer Should Bookmark

Markdown represents headings with one to six hash symbols followed by a space. A single hash is an H1, two is an H2, and so on through six. Always leave a space after the hashes, because ##Heading will not render as a heading in most parsers while ## Heading will. Most codebases use only one H1 per document for SEO and accessibility reasons, and reserve H2 through H4 for sections and subsections. Some flavors also support an alternative syntax where you underline the heading with equals signs for H1 or dashes for H2, but this is rarely used in modern documentation. When you are writing for a static site generator, the heading level often feeds into the table of contents, so keep the hierarchy consistent. Skipping from H2 to H4 may render fine but will confuse screen readers and TOC generators.

For inline emphasis, Markdown gives you several overlapping options. Wrapping text in single asterisks or single underscores produces italic text, while double asterisks or double underscores produce bold. The strikethrough extension, which uses double tildes, is widely supported after being popularized by GitHub Flavored Markdown. Inline code is wrapped in single backticks, and if you need a backtick inside the code, you can use double or triple backticks as the delimiter. The choice between asterisks and underscores is mostly stylistic, but asterisks are safer when you are dealing with text that contains underscores, like variable names or URLs. Be careful with word-internal underscores: most parsers treat them as literal characters inside a word, which is why snake_case identifiers render correctly.

Lists are the most error-prone part of Markdown. Unordered lists start with a dash, asterisk, or plus followed by a space. Ordered lists start with a number followed by a period. The number you write does not actually determine the output number in strict Markdown, since the first item becomes 1, the second becomes 2, and so on, but most renderers now respect the actual numbers you type. Nested lists require a consistent indentation level, usually two or four spaces depending on the parser. The single most common bug is forgetting to leave a blank line between a paragraph and the list that follows it. Without that blank line, many parsers treat the list items as part of the paragraph and refuse to render the bullets at all.

Links come in two flavors: inline and reference. An inline link uses the pattern [text](url), with the URL optionally followed by a title in quotes. A reference link splits the link into two parts: [text][id] where you write the text, and elsewhere in the document [id]: url followed by an optional title. Reference links are useful when you have a long URL that would break the flow of a paragraph, or when you reuse the same link many times. Images follow the same syntax but with a leading exclamation mark: . For complex documents, reference-style images keep the source readable. One pitfall worth knowing: the alt text is required for accessibility, and it should describe the image rather than just repeat the surrounding paragraph.

Code in Markdown is either inline or fenced. Inline code, as mentioned earlier, is wrapped in single backticks. Fenced code blocks use three backticks at the start and end, and you can specify a language after the opening fence to enable syntax highlighting. The language hint is optional, but omitting it means the renderer will fall back to plain text and you lose color coding. Common values include js, ts, python, bash, json, and yaml, though many renderers also accept longer aliases like javascript. For code that itself contains backticks, you can use four or more backticks as the fence so the inner content is treated literally. Avoid indenting code with four spaces unless you are targeting a parser that only supports the original Markdown syntax, because the fenced form is more readable and easier to copy.

Blockquotes start with a greater-than sign followed by a space. They can be nested with additional levels of the marker, and they can contain other Markdown elements like lists or code blocks. Horizontal rules are produced by three or more hyphens, asterisks, or underscores on a line by themselves. Tables, originally a GitHub extension, are now widely supported. They use pipes to separate columns and a row of dashes to separate the header from the body. Alignment can be set by placing colons in the dash row: a colon on the left for left-aligned, on the right for right-aligned, and on both sides for centered. Tables are handy for small reference data but become unwieldy for anything with many columns or long cell content. For complex layouts, fall back to HTML.

The most common Markdown pitfalls are syntactic. Forgetting a blank line before a list will collapse the list into the preceding paragraph. Mixing tabs and spaces for indentation will break nested lists in unpredictable ways. Putting a pipe character inside a table cell requires escaping with a backslash. HTML and Markdown can be mixed, but the parser stops processing Markdown inside a block-level HTML element, so anything you write between a div opening and closing tag is treated as literal HTML. The safest approach is to use HTML only for things Markdown cannot express, like a details disclosure widget, and stick to Markdown for everything else. When in doubt, preview your Markdown before publishing, because the rendering differences between CommonMark, GitHub Flavored Markdown, and various static site generators are real.

GitHub Flavored Markdown adds several extensions that have become near-universal. Task lists are created by writing - [ ] or - [x] inside a list item, and they render as clickable checkboxes on GitHub. Strikethrough with double tildes is part of GFM and is supported by most modern renderers. Autolink turns bare URLs into clickable links without requiring the angle-bracket syntax. Tables, as mentioned, were popularized by GFM. There are also extensions that are less universal: footnotes, definition lists, and math notation through LaTeX. If you are writing for a specific platform, check which extensions it supports before relying on them. For portable documentation, stick to the CommonMark core plus the most established GFM extensions, and your Markdown will render correctly almost everywhere.