The Fundamentals of Markdown

About this paper

Markdown is a set of formatting conventions John Gruber published on his blog on March 9, 2004, implemented as a single Perl script, licensed BSD-style, and never formally specified. Twenty-two years later it is the default serialization format of the largest computing shift since the web — the thing models are trained on, the thing they emit, the thing every agent runtime reads its instructions from, and the thing your documentation is quietly being converted into whether you published it that way or not.

Anil Dash — who was the product manager for Movable Type, the blogging platform Gruber’s script first shipped as a plugin for — calls markdown “the control plane for AI”: you can have the most cutting-edge frontier model from a trillion-dollar company, and you’re making a plain text file to orchestrate it.

That is a strange outcome for a Perl script, and the conventional explanation — “it’s simple” — is wrong in an important way. Plenty of simple formats lost. Markdown won on a property Gruber named as his primary design goal and almost nobody else optimized for: it is readable when nothing parses it. That single property is why it survived a decade with no specification, and it is the exact reason a language model handles it better than any structured alternative. This paper is the complete reference — the origin and its ancestors, the standardization fight and the naming dispute behind it, every dialect and its steward, the platforms that made .md ubiquitous, the named repository files and where each convention actually came from, and the current explosion of llms.txt, AGENTS.md and SKILL.md with the ownership column filled in. It closes with a measured census rather than a claim: what 26,099 API providers in the APIs.io catalog actually publish, including how many ship an llms.txt (I fetched every one), how many publish agent skills, and how thoroughly plain .md has beaten every extension that tried to improve on it.

What's inside

1. What markdown actually is — and the design goal that won
2. Where it came from — 2004, and the four formats it borrowed
3. The twenty-year specification vacuum
4. The dialects — who extended it, and with what
5. The engines and the platforms
6. The named files — the repo convention layer
7. The agentic file layer — the current explosion
8. What the catalog actually shows
9. Anti-patterns I watch for
10. Self-assessment
11. Where this is going
12. Source conversation — Anil Dash
13. Appendix — The .md file reference

What you get for $50.00