Technical Beauty — Episode 32
You have never opened a formatting toolbar to read a README. You have never needed to. The bold was bold, the heading was # Heading, the link was here, and your eyes did the rendering without any help. One has become so used to this that one forgets how recently it was not the case.
Two Men, One Blog Post, One Perl Script
On 15 March 2004, John Gruber posted "Introducing Markdown" on his blog Daring Fireball. He credited Aaron Swartz as his sole beta-tester and acknowledged that many of the syntax decisions came directly from Swartz. In particular, the hash-prefix heading syntax came from Swartz's 2002 atx language, a shorthand for writing HTML that Swartz had been refining for two years. Swartz also wrote html2text, the reverse converter that turns HTML back into Markdown.
That was the entire launch. Two men, one blog post, one Perl script.
The Design
The original reference implementation (Markdown.pl) was approximately 1,400 lines of Perl. It processed text through regular expressions. There was no lexer, no parser, no abstract syntax tree. It was not rigorous. It was, rather deliberately, only as rigorous as it needed to be.
The design goal was a single sentence, which one rather admires:
A Markdown-formatted document should be publishable as-is, as plain text, without looking like it has been tagged or formatted with special instructions.
Readability came first. Everything else came second, if at all. Gruber stopped active development on the reference implementation in December 2004. He did not add a plugin system. He did not start a foundation. He published his thing, and left it.
The Elegance
The syntax is aggressively un-special. Emphasis is asterisks. Headings are hashes. Links are brackets followed by parentheses. Lists are dashes or asterisks. Code is indented, or fenced in backticks. Block quotes are greater-than signs, because that is how email has quoted messages since the 1980s. One can teach the entire language to a non-programmer in about ten minutes.
The insight is that all of these conventions pre-date Markdown. Gruber did not invent them. He noticed that people already used asterisks for emphasis in plain-text email; that hashes already felt like section markers because of Twitter, of IRC, of notebooks; that brackets and parentheses already appeared in footnote syntax; that dashes were already how people marked bullet points in the absence of rendering. Markdown is a codification of how people were already writing, not an invention of how people should write.
This is the difference between a language and a convention made explicit.
The Fragmentation
Because Gruber's specification was informal prose rather than a formal specification, and because Markdown.pl had known edge-case bugs that he had stopped maintaining, implementations diverged. PHP Markdown, Python-Markdown, Showdown (JavaScript), Marked, and dozens of others each handled ambiguities differently. Writing a document that rendered identically across them was, for almost a decade, a minor dark art.
GitHub Flavored Markdown (GFM), introduced in 2009 and formally specified in 2017, added tables, task lists, strikethrough, and autolinks. GFM is the flavour most developers now actually mean when they say "Markdown". It has become, effectively, the default.
The Standardisation
In 2012, John MacFarlane, the author of Pandoc, and Jeff Atwood, the co-founder of Stack Overflow and Discourse, began work on an unambiguous specification. The effort drew in contributors from GitHub, GitLab, Reddit, and Stack Exchange. In September 2014, they launched CommonMark: a formal specification with over 500 conformance tests, reference implementations in C and JavaScript, and unambiguous rules for every edge case.
Gruber objected to the original name, "Standard Markdown". Atwood published a public apology, the project was renamed to CommonMark, and Gruber eventually accepted the name. Sharing of text was, in the end, more important than territory. This is itself rather a Markdown-ish outcome.
The Proof
Twenty-two years after the Perl script and the blog post, Markdown is the default writing surface of the modern internet. GitHub, GitLab, Reddit, Discord, Stack Overflow, and Swift use CommonMark-based rendering. Notion, Obsidian, Logseq, and a generation of personal-knowledge-management tools store their content as Markdown by default. For the third year running, the 2025 Stack Overflow Developer Survey lists Markdown as the most admired documentation format.
ChatGPT, Claude, and every other major large language model emit Markdown by default, because it is what humans now read. The generation of developers who learned to write in GitHub READMEs in the 2010s became the audience that LLM outputs are now tuned for. The feedback loop is complete: Markdown formed the way humans write online, and now LLMs write back to humans in Markdown.
Aaron
Aaron Swartz died in January 2013, aged twenty-six, during a federal prosecution for downloading academic papers from JSTOR. He was, by any reasonable measure, one of the most consequential programmers of his generation: co-author of the RSS 1.0 specification at age fourteen, principal architect of the Creative Commons technical infrastructure, founder of the web.py framework, co-founder of Reddit, and the "sole beta-tester" whose feedback shaped Markdown's syntax during its year of design.
The technologies he helped shape continue to do what they were meant to do, which is to make written information easier to share, read, and preserve. One cannot quite read a README without thinking of him.
The Point
Markdown was not engineered for scale. It was engineered for readability. It did not aim for standards-body approval. It did not aim for being taught in schools. It aimed for something much smaller: a syntax that a writer could use without feeling they were tagging their own prose.
Twenty-two years later, plain text won. One rather thought it might.
Read the full article on vivianvoss.net →
By Vivian Voss — System Architect & Software Developer. Follow me on LinkedIn for daily technical writing.
Top comments (0)