Cheatsheet
Markdown syntax, from basics to GitHub extras
CommonMark first, then the GitHub Flavored Markdown extensions that most people assume are standard and are not: tables, task lists, strikethrough, footnotes, and alerts. The final section covers what breaks between renderers, which is where the real time goes.
Text and inline formatting
| Syntax | Result |
|---|---|
| *italic* or _italic_ | Emphasis. Asterisks are safer inside words, where underscores are ignored. |
| **bold** | Strong emphasis. |
| ***bold italic*** | Both at once. |
| ~~struck through~~ | Strikethrough. A GFM extension, not CommonMark. |
| `inline code` | Monospace, with no formatting applied inside. |
| `` code with a ` tick `` | Use more backticks on the outside than appear inside. |
| two trailing spaces | A hard line break inside one paragraph. Invisible, which is why people hate it. |
| a trailing backslash | The same hard break, and visible in the source. Prefer it. |
| a blank line | Starts a new paragraph. A single newline is just a space. |
| --- or *** or ___ | Horizontal rule. Needs a blank line above it or it may become a heading. |
| \* \_ \# \[ \` \| | Backslash escapes for characters that would otherwise be syntax. |
| <!-- a comment --> | HTML comment. Invisible in the rendered output and in most previews. |
| :tada: :warning: | Emoji shortcodes. A GitHub feature, not part of any Markdown spec. |
Gotcha: the two space hard break is the most fragile thing in Markdown. Editors that trim trailing whitespace on save silently delete it, and code review shows nothing. Use the trailing backslash, or restructure into two paragraphs.
Headings, lists, and quotes
| Syntax | Result |
|---|---|
| # H1 through ###### H6 | Headings. The space after the hashes is required by CommonMark. |
| Title on one line, then === | Setext H1. Underlining with dashes gives H2. Legacy but valid. |
| - item | Unordered list. Asterisk and plus also work; pick one and stay consistent. |
| 1. item | Ordered list. Numbering is renumbered on render, so every line can say 1. |
| 1) item | Also valid. Switching the delimiter starts a new list. |
| 4. item | The first number sets the start, so a list can begin at four. |
| two space indent under a dash | Nested list item. Align with the parent's text, not its marker. |
| blank line between items | Makes the list loose, wrapping each item in a paragraph and adding spacing. |
| - [ ] todo | Unchecked task list item. GFM only, and it must be inside a list. |
| - [x] done | Checked item. On GitHub these render as clickable checkboxes in issues. |
| > quoted text | Blockquote. Repeat the marker to nest. |
| > - a list inside a quote | Blockquotes contain any block content, including code and tables. |
Gotcha: to put a paragraph or a code block inside a list item, indent it to line up with the item's text, which is two spaces after a dash and three after "1. ". Miss it by one space and the block escapes the list.
Links, images, and code
| Syntax | Result |
|---|---|
| [text](https://example.com) | Inline link. |
| [text](https://example.com "Title") | Inline link with a title attribute shown on hover. |
| [text][ref] then [ref]: https://... | Reference link. Keeps long URLs out of the prose. |
| <https://example.com> | Autolink. The URL becomes its own link text. |
| https://example.com | A bare URL. Linked automatically by GFM, left as text by strict CommonMark. |
| [section](#heading-text) | Anchor link. GitHub slugs are lowercase with spaces turned into hyphens. |
|  | Image. Identical to a link with a leading exclamation mark. |
| [](https://target) | A clickable image: an image nested inside a link. |
| three backticks then a language | Fenced code block with syntax highlighting. |
| four or more backticks | A fence that can contain three backtick fences. Essential when writing about Markdown. |
| ~~~lang | Tilde fences. Same behavior, and they nest with backtick fences cleanly. |
| four space indent | Legacy indented code block. No language tag, and it collides with list indentation. |
Gotcha: a relative image path resolves against the rendered page's URL, not the file's location, so an image that works in your editor can 404 on the site. Use a repository absolute path, or a full URL, for anything that has to render in more than one place.
GitHub Flavored Markdown extensions
None of the following is in the CommonMark spec. Every one of them is worth using, and every one of them can render as literal text somewhere else.
Tables
| Command | Does | Notes |
| ------------ | :-------------: | -------: |
| `git status` | Shows state | Default |
| `git add -p` | Stages hunks | Best one || Rule | Detail |
|---|---|
| --- / :--- / :---: / ---: | Default, left, center, and right alignment for that column. |
| Header row required | A table with no header row does not render as a table at all. |
| Column count is fixed by the header | Extra cells in a body row are dropped; missing ones render empty. |
| \| inside a cell | Escape a literal pipe, even inside inline code, or the cell splits. |
| No block content in cells | No lists, no code fences, no paragraphs. Inline formatting and a br tag only. |
| Outer pipes optional | Leading and trailing pipes are cosmetic. Keep them; the source stays readable. |
Alerts, footnotes, and collapsible sections
> [!NOTE]
> Useful information a reader should know.
> [!TIP]
> Optional advice that helps.
> [!IMPORTANT]
> Information necessary for success.
> [!WARNING]
> Urgent content needing immediate attention.
> [!CAUTION]
> Advises about risks or negative outcomes.
Text with a reference.[^why]
[^why]: The footnote body, collected at the end of the document.
<details>
<summary>Click to expand</summary>
Markdown inside needs a blank line after the summary tag.
</details>| Feature | Detail |
|---|---|
| [!NOTE] and friends | Five types only, uppercase, on the first line of a blockquote. Anything else renders as a plain quote. |
| [^label] | Footnote reference. The label can be a word, not just a number. |
| [^label]: text | The definition. Position is irrelevant; footnotes always render at the bottom. |
| details and summary | Plain HTML, so it works anywhere HTML is allowed. A blank line restores Markdown parsing inside. |
| a mermaid code fence | Rendered as a diagram on GitHub and GitLab. Elsewhere it stays a code block. |
| math between dollar signs | LaTeX rendering on GitHub: one dollar sign inline, two for a display block. |
| issue and commit autolinks | A hash plus a number, or a bare commit SHA, becomes a link inside a GitHub repo. |
| definition lists | Not supported. They exist in Pandoc and PHP Markdown Extra only. |
Gotcha: alert syntax is exact. It must be the first line of the blockquote, the keyword must be uppercase, and there must be no text on that line. Get any of it wrong and you get an ordinary quote with a bracketed word in it, with no warning.
Portability and frontmatter
| Feature | Where it works |
|---|---|
| Headings, lists, links, code fences | Everywhere. This is CommonMark and it is safe. |
| Tables, task lists, strikethrough | GitHub, GitLab, most static site generators, most editors. Not strict CommonMark. |
| Footnotes | GitHub and most generators, usually behind a plugin. |
| Alerts | GitHub, and GitLab with its own syntax. Nowhere else. |
| Raw HTML | Allowed by the spec, stripped by GitHub's sanitizer and by most comment fields. |
| Automatic heading anchors | GitHub and most generators, but the slug rules differ between them. |
| YAML frontmatter | Every static site generator. GitHub renders it as a table in some views. |
| MDX components | Only in an MDX pipeline. Plain Markdown renderers choke on the import lines. |
---
title: "Choosing a stack in 2026"
description: "Why boring defaults keep winning."
date: 2026-08-07
tags: [stacks, architecture]
draft: false
---
# Choosing a stack in 2026
Body starts here.Gotcha: frontmatter must be the very first thing in the file, with the opening dashes on line one. A blank line or a stray byte order mark above it turns the whole block into a horizontal rule followed by visible text.
Conventions that keep files reviewable
| Convention | Why |
|---|---|
| One H1 per file, at the top | Matches how every renderer builds a document outline, and how search engines read a page. |
| Never skip a heading level | An H2 followed by an H4 breaks the outline for screen readers and table of contents generators. |
| One sentence per line | Diffs point at the sentence that changed instead of at a whole reflowed paragraph. |
| Always tag your code fences | Syntax highlighting, and linters that can check the snippet. |
| Reference links for repeated URLs | One place to update when the link moves. |
| Blank line around every block | Headings, lists, fences, and tables all need one. Most rendering surprises trace back to a missing blank line. |
| markdownlint in CI | Catches the missing blank lines, skipped levels, and stray hard breaks before review does. |
| Plain ASCII punctuation | Straight quotes and regular hyphens survive every terminal, diff tool, and copy paste. |
Keep going
Most Markdown you write ends up in a repository, so the Git cheatsheet is the natural companion, and the regex cheatsheet covers the find and replace patterns for cleaning up a pile of old files.
Publishing it is a static site problem: see the static site stack guide and Next.js vs Astro. The cheatsheet index lists every reference on this site.