Markdown Cheat Sheet

Table 1: Headings

Headings give a document its structure, and Markdown offers two ways to write them. The hash-prefix ATX style (# through ######) is by far the most common and covers all six levels, while the older Setext style underlines text for the top two. Custom IDs let you link straight to a specific section.

Table 2: Text Emphasis

The everyday formatting that makes prose readable — bold, italic, and their combination, all built from asterisks or underscores. A handful of these go beyond core Markdown: strikethrough is a GFM extension, while highlight, subscript, and superscript usually rely on extended syntax or a fall-back to raw HTML tags.

Table 3: Paragraphs and Line Breaks

One of Markdown's most common surprises is that pressing Enter doesn't always create a new line — paragraphs are separated by blank lines, and a line break within a paragraph needs explicit help. These options show the three ways to force that break: trailing spaces, a backslash, or an HTML <br> tag.

Table 4: Lists

From simple bullets to nested hierarchies and GitHub's interactive checkboxes, lists are everywhere in Markdown. The detail that trips people up most is indentation — sub-items and continuation paragraphs need 4 spaces or a tab to stay attached to their parent item.

Table 5: Links

Links come in more flavors than most people realize. Inline links are the workhorse, but reference-style links keep dense text readable by moving URLs out of the way, relative links keep repository docs portable across branches and forks, and autolinks turn a bare URL into a clickable one automatically.

Table 6: Images

Image syntax mirrors link syntax with a leading !, and the same reference-style and relative-path tricks apply. Two practical notes stand out: always write meaningful alt text for accessibility, and because Markdown can't resize images, reach for a raw <img> tag when you need to control width.

Table 7: Code

Showing code is one of Markdown's most-used jobs. Single backticks handle inline snippets, while fenced blocks with triple backticks wrap whole listings — and adding a language identifier after the opening fence unlocks syntax highlighting. The older indented-block style still works but fenced code is almost always the better choice.

Table 8: Blockquotes

A leading > turns a line into a quote, useful for citing sources or setting text apart. Blockquotes can span multiple paragraphs, nest several levels deep, and even contain other Markdown like headings and lists.

Table 9: Horizontal Rules

A horizontal rule draws a divider line to separate sections of a document. Three or more hyphens, asterisks, or underscores on their own line all produce the same thematic break — pick whichever you find most readable in the raw source.

Table 10: Tables

Tables are a GFM extension built from pipes and hyphens, with a separator row defining the header. Colons in that separator control column alignment — left, center, or right — and an HTML entity lets you slip a literal pipe character into a cell without breaking the structure.

Table 11: Escaping Characters

Sometimes you want a character that Markdown treats as syntax to show up literally — an asterisk that isn't italics, or a backtick that isn't code. A backslash before the character escapes it, and wrapping symbols in backticks is an alternative that displays them verbatim.

Table 12: HTML Embedding

When Markdown alone can't do what you need, you can drop raw HTML right into the document. This unlocks features with no native syntax — styled spans, collapsible <details> sections, and hidden comments — though block-level HTML needs blank lines around it to render correctly.

Table 13: YAML Front Matter

Front matter is a YAML block fenced by triple dashes at the very top of a file, carrying metadata about the document rather than its content. Static site generators and tools like Pandoc, Jekyll, and Hugo read these fields — title, author, date, tags — to drive page titles, exports, and site behavior, and you can add arbitrary custom keys for your own tooling.

Table 14: Extended Syntax — Footnotes

Footnotes let you attach a reference marker in your text to a note that renders at the bottom of the page — invaluable for citations and asides in long-form writing. You place the [^id] marker inline and define its content separately, using either numbers or word labels, and a footnote can even span multiple indented paragraphs.

Table 15: Extended Syntax — Definition Lists

Definition lists pair a term with one or more definitions — the format you'd use for a glossary. The definition line starts with a colon, and a single term can carry several definitions. It's an extended-syntax feature, so not every parser supports it.

Table 16: Extended Syntax — Abbreviations

Define an abbreviation once and every occurrence of it in the document gets a hover tooltip spelling out the full term — handy for keeping acronym-heavy technical docs readable. It's an extended-syntax feature supported by parsers like Python-Markdown.

Table 17: Extended Syntax — Emoji

There are two ways to get emoji into Markdown: type a shortcode like :rocket: that the platform converts, or paste the actual Unicode character. Shortcodes are convenient but their names vary between platforms, whereas pasted Unicode emoji work everywhere.

Table 18: Math Expressions

Many platforms now render LaTeX math inside Markdown via MathJax or KaTeX — single dollar signs for inline expressions, double for centered display blocks. The rest of the entries are a quick LaTeX primer for the notation you'll reach for most: fractions, roots, summations and integrals, and Greek letters.

Table 19: Mermaid Diagrams

Mermaid lets you describe diagrams as plain text inside a fenced code block, and platforms like GitHub, GitLab, and Obsidian render them as real graphics. It's a remarkably versatile toolkit — the diagram types here range from flowcharts and sequence diagrams to Gantt charts, class and ER diagrams, pie charts, and state machines.

Table 20: GitHub Flavored Markdown (GFM) Extensions

These are GitHub-specific niceties that only work within GitHub itself. Typing @username pings a person, #123 links to an issue, and a pasted commit SHA becomes a link — small touches that make conversations in issues and PRs flow. Note that GFM also strips certain raw HTML tags for security.

Table 21: GitHub Alerts (Callouts)

Alerts are colored callout boxes that draw the eye to something important. Built on blockquote syntax with a [!TYPE] marker, the five flavors each carry their own color and tone — from a neutral blue NOTE up to a red CAUTION warning of real risk — so readers can gauge severity at a glance.

Table 22: Markdown Variants and Flavors

There's no single Markdown — the original spec left gaps, and different communities filled them in different ways. CommonMark is the unambiguous baseline most tools now follow, GFM is the dominant developer dialect, and the rest (Pandoc, MultiMarkdown, MDX, and others) each add features for academic writing, document conversion, or interactive React components.

Table 23: Best Practices

Markdown that renders correctly isn't always Markdown that's pleasant to maintain. These habits — blank lines around headings, consistent list markers, fenced code over indented, alt text on every image, and semantic line breaks for cleaner diffs — keep your source readable and portable across the widest range of parsers.

Table 24: Common Pitfalls and Gotchas

The subtle traps that make Markdown "not render right" — and they catch experienced writers too. A missing blank line before a list, too-shallow nested indentation, underscores triggering accidental italics inside snake_case, blank lines breaking a table, or a dollar sign mistaken for math: knowing these failure modes saves a lot of confused debugging.

Table 25: Advanced Techniques

Once you're comfortable with the basics, these techniques squeeze more out of the syntax — collapsed reference links, definitions placed anywhere in the file, lazy blockquote continuation, hand-built tables of contents from heading anchors, and Obsidian-style wikilinks. They're the touches that separate workmanlike Markdown from genuinely polished documents.

Table 26: Editor and Tool Support

Markdown's reach comes from its ecosystem. This roundup spans the tools you'll actually write and ship with — VS Code and Typora for editing, Obsidian for linked notes, Pandoc for converting to anything, and static site generators like Jekyll, Hugo, and Quarto for publishing — so you can match the right tool to whether you're taking notes, building docs, or producing scientific output.