Core answer: Markdown is plain-text formatting that converts to HTML: # heading, bold, *italic*, - lists, [text](url) links, code, > quotes, --- rules, | tables |. It renders identically everywhere the CommonMark/GFM spec is followed — but flavors differ (tables and footnotes are GFM, not original Markdown). Learn 12 syntax marks and you're fluent.

The 12-mark survival kit

SyntaxRenders
# ## ###headings h1–h6
bold / __bold__strong
*italic* / _italic_emphasis
~~strike~~ (GFM)strikethrough
- item / 1. itembullet / ordered list
[text](https://…)link
![alt](img.png)image
inlinecode span
```lang fenced blockscode block
> quoteblockquote
---horizontal rule
abtable (GFM)table

The gotchas that bite daily

  1. Line breaks: a single newline does NOT break a line; end a line with two spaces or a blank line for a new paragraph.
  2. Nested lists: indent 2 (or 4, flavor-dependent) spaces consistently; mixing tabs and spaces breaks nesting.
  3. Underscore italics inside words: mid_word_italics renders literally in GFM (intraword _ disabled) — but not in all flavors; prefer *asterisks* for italics.
  4. Raw HTML: most renderers pass HTML through — powerful, and an XSS hole if you render user input without sanitizing.
  5. Table pipes inside cells: escape as \| or use code spans.

Flavor map

  • Original (Gruber 2004): headings, emphasis, lists, links, images, code, quotes. No tables.
  • CommonMark: the rigorous spec — resolves ambiguity.
  • GFM (GitHub): CommonMark + tables, task lists (- [ ]), strikethrough, autolinks, footnotes.
  • Platform quirks: WeChat editors, Notion, DingTalk each subset/extend differently — paste and verify.

Worked examples

Example 1 — README structure. # Title → badges → ## Install (code block) → ## Usage (code block) → table of options → license. 90% of good READMEs are this skeleton.

Example 2 — Docs-as-code. Documentation in Markdown under git: diffs are reviewable, PRs apply, and static-site generators (VitePress, Docusaurus) render the same files into sites.

Example 3 — The migration trap. Converting Word → Markdown via pandoc preserves 90%; manual cleanup concentrates in tables, footnotes, and images — budget time accordingly.

Common mistakes and myths

  1. Expecting WYSIWYG fidelity — Markdown intentionally can't do colored text, exact fonts, or merged cells; that's a feature (portability), use HTML islands sparingly when unavoidable.
  2. Setext vs ATX confusion — underlined === headings (Setext) are valid but ATX (#) dominates; mixing both in one doc hurts diffs.
  3. Assuming tables are universal — raw CommonMark has no tables; know your renderer's flavor before relying on them.
  4. Over-nesting — beyond 3 heading levels and 2 list levels, structure rots; split documents instead.
  5. Security amnesia — rendering user Markdown without sanitization = stored XSS; always run a sanitizer (DOMPurify) on untrusted input.