Understanding why developers write in markdown starts with a simple question: why did a format created in 2004 by a blogger and a teenager become the default writing tool for 180 million developers and every major AI system on the planet? The answer is not about technology preferences or programmer culture. It is about a set of practical qualities that no other format has managed to combine: human readability, zero dependencies, version control compatibility, and universal portability.
This is the story of how markdown went from a Perl script on a personal blog to the invisible infrastructure behind GitHub, Reddit, Stack Overflow, ChatGPT, Claude, and billions of documents.
Why developers started writing markdown: the 2004 origin story
In March 2004, John Gruber published the first version of Markdown on his blog, Daring Fireball. He was not a software engineer. He was a tech writer and commentator who spent his days writing for the web and found the experience of composing in raw HTML intolerable. As Gruber described it, writing in HTML "made it hard to proofread my work" because the angle brackets, closing tags, and entity references obscured the actual content.
His collaborator was Aaron Swartz, who was 17 years old at the time. Swartz, already known for his work on RSS 1.0 and later for co-founding Reddit, contributed to the syntax design and helped build the reference implementation: a Perl script called Markdown.pl that converted plain text to HTML.
The design philosophy was deliberately constrained. Gruber wrote that the syntax was "borrowed from conventions people already used in plain text emails." Asterisks for emphasis, hash marks for headings, dashes for lists, and angle brackets for blockquotes were patterns that people had been using informally for years. Markdown just formalized them into a consistent system with a reliable conversion path to HTML.
Here is what that looked like:
# Project Update
The new **authentication system** is ready for testing.
Key changes:
- OAuth 2.0 support added
- Session tokens now expire after 24 hours
- Rate limiting on `/api/login` (10 req/min)
> "The best security is the kind users never notice."
See the [API documentation](https://docs.example.com) for details.
Even without rendering, that text is completely readable. You know exactly what is a heading, what is bold, what is a list, and what is a quote. That was the entire point. Markdown was designed to be readable as plain text, not just as rendered output.
Why developers chose markdown over everything else
Developers had options. Rich text editors existed. HTML was well-understood. LaTeX covered academic publishing. Textile and reStructuredText offered similar plain-text-to-HTML conversion. Markdown won for five specific reasons.
It requires nothing
A markdown file is a plain text file with a .md extension. You can create one with echo "# Hello" > notes.md. You can read it with cat notes.md. You can edit it with Vim, VS Code, Notepad, TextEdit, or any text editor on any operating system ever made. There is no application to install, no account to create, no license to purchase, and no format to import.
For developers who already live in terminals, text editors, and command lines, this is not a minor convenience. It means documentation lives in the same environment as code, navigable with the same tools, editable with the same keystrokes.
It diffs cleanly in version control
This is the reason that most developers cite first. Markdown files produce readable, meaningful diffs in Git:
## Deployment Guide
- Run `npm run build` to create the production bundle.
+ Run `npm run build:prod` to create the production bundle.
+ The build will fail if environment variables are not set.
Upload the contents of `dist/` to the CDN.
That diff is immediately understandable. You can see what changed, why it might matter, and whether it is correct. Try diffing a Word document or a Google Doc export. The binary format produces meaningless output, and the XML internals are thousands of lines of structural markup that bury the actual content change.
Git, the version control system used by virtually every software team, was built for tracking changes to text files. Markdown is a text file. The synergy is natural and complete: branching, merging, blame annotations, pull request reviews, CI/CD hooks, and automated changelog generation all work out of the box.
It is readable without rendering
Most markup languages optimize for the output. HTML looks terrible as source code. LaTeX is dense and symbol-heavy. Even reStructuredText, which was designed for readability, uses underlines and directives that feel heavier than markdown's symbols.
Markdown optimizes for the source. A markdown file on GitHub, in a terminal, in an email, or printed on paper is readable by a human who has never heard of markdown. The formatting symbols are lightweight enough to read through, not around.
It maps to HTML (and everything else)
Markdown was created to generate HTML, and that direct mapping means every heading, paragraph, list, link, and image has an unambiguous HTML equivalent. This made adoption trivial for web developers: markdown was not a new abstraction to learn but a shorthand for something they already knew.
Over time, tools extended this mapping beyond HTML. Pandoc (created by John MacFarlane, who later led the CommonMark effort) can convert markdown to PDF, DOCX, LaTeX, EPUB, and dozens of other formats. Unmarkdown™ converts markdown to formatted output for Google Docs, Word, Slack, OneNote, email, and web pages. The content stays the same; only the destination changes.
The ecosystem compounds
Once GitHub adopted markdown for README files, issues, and pull requests, the network effect was unstoppable. Every developer on GitHub (now over 180 million) writes markdown. Every open-source project has a README.md. Every pull request description is markdown. Every issue comment is markdown.
This means every developer learns markdown as a side effect of using GitHub. There is no "learning markdown" step. You learn it by participating in the software development ecosystem, one pull request at a time.
The fragmentation problem and CommonMark standardization
Gruber's original markdown specification was, by his own description, "deliberately informal." There was no test suite, no edge case documentation, and no formal grammar. The spec was a blog post with examples, and the reference implementation was a single Perl script.
This informality created a problem. When other developers built their own markdown parsers (and hundreds did), they had to make decisions about ambiguous cases. What happens when you nest blockquotes inside lists? When a heading immediately follows a paragraph without a blank line? When asterisks appear in the middle of a word?
Different parsers made different decisions. GitHub, Reddit, Stack Overflow, PHP Markdown Extra, MultiMarkdown, and Pandoc all diverged. As Karl Voit wrote in August 2025: "There is no single definition of Markdown. Instead there is a zoo of Markdown flavors."
The fragmentation was real but often overstated. For 90% of daily use (headings, bold, italic, links, lists, code blocks, images), every parser agreed. The disagreements were at the edges: obscure nesting scenarios, whitespace handling, and HTML passthrough rules.
CommonMark was the solution. In 2014, John MacFarlane (the creator of Pandoc) and Jeff Atwood (co-founder of Stack Overflow) launched the CommonMark specification project. Their goal: a formal, unambiguous spec with over 500 conformance tests that any parser could implement and verify against.
CommonMark took years to stabilize, but adoption was decisive. GitHub adopted it (extending it with GFM, or GitHub Flavored Markdown). GitLab adopted it (extending it with GLFM). Reddit, Discourse, Stack Exchange, Codeberg, and dozens of other platforms followed. CommonMark became the baseline that everyone agreed on, with platform-specific extensions layered on top.
The result in 2026: markdown is more standardized than it has ever been. The "zoo of flavors" still exists at the extension layer (tables, task lists, math, diagrams), but the core syntax is stable, tested, and interoperable.
Markdown and GitHub: the developer adoption engine
GitHub's role in markdown adoption cannot be overstated. The platform did not just use markdown; it made markdown the default language of software collaboration.
The numbers tell the story. GitHub hosts over 630 million repositories. In 2025 alone, 121 million new repositories were created, roughly 230 new repos per minute. Every single one of those repositories can contain a README.md that GitHub automatically renders on the repository's homepage.
GitHub Flavored Markdown (GFM) extends CommonMark with features developers requested:
- Tables (pipe-delimited, with alignment)
- Task lists (
- [x]and- [ ]checkboxes) - Strikethrough (
~~deleted text~~) - Autolinks (bare URLs become clickable)
- Syntax highlighting (language-tagged fenced code blocks)
- Footnotes (added in 2021)
- Math (added in May 2022, after being requested for over 8 years)
- Mermaid diagrams (added alongside math support)
- Alerts (NOTE, TIP, IMPORTANT, WARNING, CAUTION callout blocks)
Each addition went through the same pattern: developers used workarounds for years, GitHub eventually formalized the syntax, and other platforms adopted the same format. GFM became the de facto standard for developer-facing markdown.
The collaboration features cemented this further. Pull request descriptions are markdown. Issue bodies are markdown. Wiki pages are markdown. Discussion posts are markdown. Code review comments support inline markdown with code snippets, task lists, and mentions. A developer on GitHub writes markdown dozens of times per day without thinking about it.
Why markdown matters beyond developers
The developer story explains how markdown became dominant in software. But the more interesting question is why it is spreading to everyone else.
Three forces are driving mainstream markdown adoption.
AI tools output markdown natively
This is the biggest catalyst. ChatGPT, Claude, Gemini, Copilot, and every other major AI assistant format their responses in markdown. When you ask ChatGPT for a project plan, you get headings, bold text, numbered lists, and tables, all in markdown syntax. When you ask Claude to write documentation, the output is a markdown file.
Anil Dash captured this in January 2026: "Nearly every bit of the high-tech world, from cutting-edge AI systems to casual code, uses the same simple plain text format. Whether you're trying to give complex instructions to ChatGPT, or you want to exchange a grocery list."
This means billions of non-developers are now encountering markdown daily, even if they do not recognize it by name. The asterisks that appear when you paste ChatGPT output into an email are markdown. The pipe characters in a broken table are markdown. The hash marks before a heading are markdown.
Every AI tool writes in markdown because it is the most efficient way to include structure in a text stream. For users, this means learning basic markdown syntax unlocks better interaction with AI tools: you can format your prompts, read AI output without confusion, and reuse generated content without reformatting.
Documentation is moving to plain text
The docs-as-code movement, which started in developer tooling, is spreading to product teams, marketing teams, and operations teams. The core idea is simple: write documentation in plain text files, store them in version control, and publish them through an automated pipeline.
Stripe, GitLab, and Cloudflare all maintain their public documentation this way. But it is not limited to tech companies. Law firms, consulting firms, and startups are adopting markdown for internal documentation because it is portable, searchable, and does not require a $10-per-seat SaaS subscription.
Publishing tools are closing the gap
The historical knock against markdown for non-developers was the last-mile problem: you could write it, but turning it into something visually polished required technical knowledge. Static site generators needed configuration files, build pipelines, and CSS. Pandoc needed command-line fluency.
That gap is closing. Markdown publishing platforms like Unmarkdown™ handle the conversion from raw markdown to styled output for any destination. Write your content, pick a visual template, and copy to Google Docs, Word, email, or a published web page. The technical barrier that kept markdown in the developer world is dissolving.
The AI connection: why developers and everyone else will write markdown
The convergence of markdown and AI is not a coincidence. It is a structural inevitability.
Large language models are text-in, text-out systems. They process tokens and generate tokens. Markdown is the lightest-weight way to encode formatting in a token stream. Compare:
Markdown: ## Project Status (3 tokens)
HTML: <h2>Project Status</h2> (7+ tokens)
Fewer tokens means faster generation and lower cost per response. At the scale of billions of daily AI interactions, that efficiency matters.
But the deeper reason is bidirectional. Markdown is not just what AI outputs; it is what AI reads best. When you give an AI tool a markdown document as context, it understands the structure instantly: headings indicate sections, lists indicate parallel items, code blocks indicate technical content, and links indicate relationships. The document your AI never forgets is almost always a markdown file.
MCP (Model Context Protocol) connections, CLAUDE.md project files, and ChatGPT custom instructions all use markdown for the same reason: it is the native interface between humans and AI systems.
This creates a feedback loop that will only accelerate. More AI output in markdown means more people learn markdown. More people writing markdown means more AI training data in markdown. More training data means better AI understanding of markdown. The cycle reinforces itself.
From developer tool to universal format
Markdown's trajectory mirrors other technologies that started in the developer world and went mainstream: version control (Git to GitHub to Google Docs version history), containers (Docker to cloud infrastructure to consumer apps), and APIs (developer integration to the app ecosystem everyone uses).
The pattern is consistent: developers adopt a tool because it solves a real problem efficiently. The tool's ecosystem grows. Platform effects compound adoption. Eventually, the tool becomes so embedded in infrastructure that non-developers use it without knowing the name.
Markdown is in the late stages of this pattern. Developers adopted it because it was readable, diffable, and portable. GitHub made it ubiquitous in software. AI made it ubiquitous everywhere else. Pandoc and publishing tools closed the formatting gap.
The format that John Gruber created in 2004 because raw HTML was hard to proofread has become, as Anil Dash described it, the "lingua franca of the internet." If you have not learned markdown yet, you are already using it. The only question is whether you recognize the syntax and can use it intentionally.
For developers, markdown was always the obvious choice. For everyone else, the case is now just as clear: it is the format that works with your tools, your AI assistants, your version control, and your publishing workflow. It costs nothing, locks you into nothing, and works everywhere.
