The Markdown Canon 📜

The documents that made markdown what it is — worth reading in the original. Annotated, in rough historical order. (For the story as a story, see the timeline.)

The founding texts (2004)

• Markdown — John Gruber's original page: the philosophy ("readable as-is") and the whole first spec. Still remarkably short. The syntax page remains a decent reference two decades on.
• Dive Into Markdown — Gruber's launch post, crediting Aaron Swartz as sounding board and first user.
• Markdown (Aaron Swartz) — Swartz's own announcement post. His earlier atx (2002) — "the true structured text format" — is a direct ancestor: hash-marks for headings come from here.

The standardisation saga (2012–2014)

• Standard Flavored Markdown — Jeff Atwood (Stack Overflow co-founder) announcing the effort to finally specify markdown's ambiguities. Published alongside John MacFarlane's spec work; Gruber objected to the name, and four days later it became…
• CommonMark — the neutral, rigorous spec (largely MacFarlane's work) that most modern implementations now build on. The spec itself is a monument to how much hidden complexity "simple" markdown contained.
• GitHub Flavored Markdown spec — GFM formalised as a strict superset of CommonMark: tables, task lists, strikethrough. The de facto dialect of the working web.

The philosophy (ongoing)

• File over app — Steph Ango (Obsidian CEO), 2023. The single best short statement of why plain files beat platforms: "the files you create are more important than the tools you use to create them." If this site has a sibling text, it's this one.
• Our own contributions to the argument: the manifesto and the markdown database pattern.

Reading order for the impatient

File over app (2 min) → Gruber's original Markdown page (10 min) → Standard Flavored Markdown (5 min, for the drama). That's the whole intellectual arc: why plain text, how markdown works, and what it took to make "simple" precise.