Markdown’s Origins and Why It Won’t Die
Markdown is so embedded in technical culture that it’s easy to forget it’s not a standard, but a design from a specific moment in web history. John Gruber released his first Perl-based parser in 2004, after collaborating with Aaron Swartz. His stated goal was narrow: “Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.” What started as a friendlier alternative to raw HTML has since become the default for technical prose — documentation, READMEs, and editor muscle memory.
That expansion beyond its original intent is precisely the problem. Two issues stand out for anyone building content tools today:
- Markdown was not designed for modern content needs.
- Markdown holds back editorial experience.
These concerns come from real-world use, not just theory. I’ve worked in agencies where we fought CMSes that locked content into complex data models. I’ve watched editors struggle with Markdown syntax and lose motivation. We spent hours building custom tag renderers that nobody ever used. I have also seen the other side: the elegance of plain-text files and the simplicity of parsing them. It makes sense that a README.md opens in any editor and renders on GitHub. There’s genuine convenience for developers — but that convenience is not universal.
To understand why Markdown is a poor default for content today, it helps to look back at how and why it was shaped.
From Simple Syntax to Many Flavors
At its core, Markdown renders HTML. Given this source:
<p>The <a href=”https://daringfireball.net/projects/markdown/syntax#philosophy”>Markdown syntax</a> is designed to be <em>easy-to-read</em> and <em>easy-to.write</em>.</p>Markdown expresses the same formatting as:
The [Markdown syntax](https://daringfireball.net/projects/markdown/syntax#philosophy) is designed to be _easy-to-read_ and _easy-to-write_.As adoption grew, so did demand for more features — footnotes, tables, and others. Gruber’s response was firm: “For any markup that is not covered by Markdown’s syntax, you simply use HTML itself.” If you want a table, write <table></table>. MDX, a later successor, applies the same principle but extends it to JSX rather than pure HTML.
The push for extensions wasn’t just about HTML, though. Many users were drawn to the ergonomics of plain text for purposes beyond web articles. MultiMarkdown, for instance, added academic writing features. Apps began accepting Markdown-like syntax without necessarily storing or rendering it as HTML.
The CommonMark Attempt
When implementations diverged, two problems arose. Writers could no longer predict what a given Markdown system would support. And developers had to choose between inconsistent parsers — the original had known quirks that made programmatic use difficult.
The most successful effort to formalize things was CommonMark, led by Jeff Atwood of Stack Overflow and Discourse fame and John MacFarlane, creator of Babelmark and pandoc. It launched as “Standard Markdown” but was renamed after Gruber objected. Today, CommonMark powers Discourse, GitHub, GitLab, Reddit, Qt, Stack Overflow, and Swift, and projects like unified.js use it to build abstract syntax trees.
But CommonMark has not unified how Markdown is used. GitHub Flavored Markdown (GFM) extends CommonMark with tables, task lists, and strikethrough. Reddit calls its format “a variation of GFM” and adds spoiler syntax. Both sides of the old argument remain right: a shared spec helps programmers; but people still want different features depend on context.
Formatting Shortcut, Not a Standard
The deeper issue is that Markdown-like syntax has become a formatting shortcut in tools like Notion, Dropbox Paper, Craft, and even Google Docs — where typing an asterisk plus space triggers a bulleted list. What’s supported, and how it behaves, varies from app to app. Slack’s mrkdown, for example, renders *this* as bold, not italic, and doesn’t support the standard [link](url) syntax, preferring <link|url> instead.
Gruber originally resisted a formal spec, believing it would shift Markdown’s focus from writers to programmers. That outcome has arguably happened with CommonMark and its derivates. Meanwhile, the everyday experience for non-technical editors depends largely on which Markdown-inspired system they happen to be using. Muscle memory built up in one tool doesn’t carry over to the next.
Markdown’s Shifting Audience
Markdown has always sat uneasily between different audiences. It began as a tool for web writers who already knew HTML, then found its most enthusiastic adopters among developers. By 2014, the publishing landscape had changed: CMS platforms like WordPress, Drupal, and Moveable Type dominated, offering browser-based rich text editors that abstracted away the underlying markup. Writers no longer needed to think in HTML, and the messy output from copy-pasting Word documents became a familiar annoyance for developers.
Today, Markdown’s core users are clearly developers and code-adjacent people. The controversy when Slack made rich text the default input mode — and the backlash that forced them to keep Markdown as an option — says a lot about how deeply the format is woven into developer culture. That attachment came at the expense of accessibility for less technical users, and it’s worth examining what that means.
The Assumptions Behind Markdown’s Popularity
Markdown’s position as the default writing format for the web is rarely questioned. It’s treated as an obvious good, and substantial effort has gone into supporting it across frameworks and tools. Challenging that consensus invites friction, but it also opens the door to a more honest look at the trade-offs.
Developer affection for Markdown usually comes down to three things:
- The comfortable abstraction of plain text files.
- A mature ecosystem of supporting tools.
- The ability to keep content close to the code workflow.
None of these are unreasonable on their own, but each carries hidden costs.
The Comfort of Plain Text
Databases have a reputation — earned or not — for being intimidating. Many frontend developers avoid backend work precisely because databases feel like a complexity sink. Plain text files are tangible and easy to reason about, especially compared to content scattered across relational tables. For simple cases like blog posts with images and links, Markdown files work fine. You can copy them, file them, and commit them to git. The content feels like yours because it lives in visible files.
But that era of local database pain is largely over. Backend-as-a-service offerings like Fauna, Firestore, Hasura, Prisma, PlanetScale, and Sanity’s Content Lake have invested heavily in developer experience. Even traditional databases are far easier to run locally than they were a decade ago. A .sql dump is as portable as a folder of files.
Content portability has more to do with structure than storage medium. WordPress is open source and fully self-hostable, with a standardized XML export format — yet anyone who has migrated a mature WordPress site knows the export barely helps. The lock-in is in how content is modeled, not where it lives.
An Ecosystem Built for Developers
Contemporary frameworks assume Markdown as a primary content format, sometimes the only one. Hugo, the static site generator behind Smashing Magazine, still requires Markdown files for paginated publishing. Next.js, Nuxt.js, VuePress, and Gatsby.js all feature Markdown prominently. GitHub defaults to Markdown for README files and even uses it in pull request comments.
There are attempts to bridge the gap for non-technical editors — Netlify CMS and TinaCMS abstract away much of the Markdown syntax, and Notion translates pasted Markdown into its own formatting. But the innovation has not favored people who don’t write Markdown syntax themselves. The effort has not trickled up the stack.
Workflow Trade-offs
For a solo developer building a blog, Markdown files reduce setup overhead. Frameworks come with built-in parsing, nothing extra to sign up for, and git gives you revision control straight out of the box. The content sits alongside code and participates in the same workflow.
Beyond that narrow scenario, things get complicated. Markdown files force content teams to interact with git, and the idea that editors should resolve merge conflicts or rebase branches is a questionable use of their time. Git is hard enough for developers who use it daily. This setup prioritizes developer experience over editor experience, and the cost is borne by the people whose primary job is content creation.
The expectations for content and editing environments have evolved significantly since Markdown’s early days. The format was designed for a different web, and stretching it to handle modern content needs — for editors and developers alike — is holding both sides back.
When Markdown Meets the Component Era
Markdown always had an escape hatch: drop into raw HTML when you needed something beyond simple rich text. That worked fine when authors were comfortable with HTML and sites were mostly articles nested inside a layout template alongside a stylesheet. CMSes and early static site generators operated the same way, injecting rendered content into templates without passing props between components.
The web has moved on. Content is no longer mostly text articles; it’s composed multimedia, interactive widgets, and specialized components like newsletter signups. The shift away from hand-authored HTML pages began in earnest in the early 2010s as SaaS companies pushed data-heavy interfaces onto the web. Frameworks like Bootstrap and Foundation emerged, standardizing class names and assuming specific DOM structures to make responsive UIs achievable. Design philosophies like Atomic Design and naming conventions like Block-Element-Modifier (BEM) cemented a component-first mindset: pages became collections of repeatable, compatible elements rather than monolithic layouts.
Markdown does not fit that model. Its content is opaque — whatever rich text you produce inside it can’t be sliced into components unless you fork the parser and customize its output. Markdown was designed to generate simple, native HTML elements targetable by stylesheets, which is still a fundamental mismatch for anyone using it to drive component-based sites.
The Embedded Web and Block Content
Content also changed shape. Much of it moved to social platforms: Facebook, Twitter, tumblr, YouTube. To pull snippets back into articles, sites turned to <iframe> embeds and then to “shortcodes” — bracket-delimited keywords with key-value attributes that identified a block type. Platform-specific customizations followed, such as Liquid templating in dev.to’s Markdown editor:
{% youtube dQw4w9WgXcQ %}Implementing shortcodes requires a customized Markdown parser plus logic to emit the correct HTML, and content creators must memorize the codes unless a toolbar inserts them. A single malformed bracket can break the page.
MDX tries to solve this with the tagline “Markdown for the component era,” letting authors interleave JSX and JavaScript with Markdown syntax. Around it, projects like Unified.js parse various syntaxes into abstract syntax trees for programmatic use — work that a standardized Markdown would simplify by reducing edge cases. MDX improves the developer experience for wiring components into content, but it doesn’t help editors, who now face significant cognitive overhead:
import {Chart} from './snowfall.js'
export const year = 2018
# Last Year’s Snowfall
In {year}, the snowfall was above average.
It was followed by a warm spring which caused
flood conditions in many of the nearby rivers.
<Chart year={year} color="#fcb32c" />That simple snippet demands knowledge of ES6 modules, JavaScript variables, JSX syntax, props, hex codes, data types, and available components — plus an editor with feedback. Authoring tools on top of MDX will likely emerge, but it feels like solving a problem that shouldn’t exist. MDX also ties content to presentation: the front-page example hard-codes a chart color as a hex value. Nothing stops you from abstracting it to color="primary", but nothing nudges you toward that decision either.
Embedding presentation in content has become a liability. It locks content into a specific design in ways subtler than a database schema, and migrating away is as painful as leaving a mature WordPress install with plugins. Separating structure from presentation is hard, and MDX makes that separation harder.
Structured Content and Front Matter
Complex sites increasingly present the same piece of content in multiple places — product descriptions across an e-commerce site, or marketing copy shared across personalized views. That requires structured content: chunked, metadata-enriched pieces that software can query for intent. A developer faced with just a “page” field of “content” can’t reliably know where to include things. Markdown limits you to expressing structure via folder organization — which breaks when content needs to live in multiple taxonomies — or via added syntax.
Jekyll, an early static site generator for Markdown, introduced Front Matter: YAML key-value metadata between dashes atop a file. Now writers handle two syntaxes, and YAML has a reputation for being finicky, particularly around implicit typing. Other SSGs and git-based CMSes adopted the convention, but layering extra syntax onto plain files to approximate structured content raises the question of who the format actually serves — and who it excludes.
Much of the web is now authored in the browser. People expect pleasant, intuitive authoring experiences without specialized syntax. Medium normalized the idea that web writing can be delightful, and Notion doubled down on block content, letting users mix many block types that go beyond Markdown and native HTML.
Notion’s own explanation of its API notes the practical problem with Markdown: “Documents from one Markdown editor will often parse and render differently in another application. The inconsistency tends to be manageable for simple documents, but it’s a big problem for Notion’s rich library of blocks and inline formatting options, many of which are simply not supported in any widely-used Markdown implementation.” Notion instead chose a JSON-based format that expresses content as structured data, arguing it makes predictable consumption easier for developers building their own presentations of Notion content.
Beyond Markdown: What Should Replace It?
Markdown's dominance has arguably stalled innovation in digital content. If we stop treating it as a default storage format, what should take its place? The more useful question is what we should expect from modern content formats and the tools that produce them.
Authoring Tools Need To Move Past Syntax
Markdown forces authors to learn syntax—and often multiple dialects and custom extensions to meet modern expectations. That's an unreasonable burden. Development energy would be better spent on accessible, intuitive editorial interfaces that output genuinely portable formats.
Good block content editors are hard to build, but viable, extensible foundations exist, such as Slate.js, Quill.js, and Prosemirror. Investing in these communities would further their progress. The expectations for authoring tools are also rising: they should be accessible, real-time, and collaborative. Why should saving require a button click? Why should concurrent edits risk race conditions or merge conflicts? Authors shouldn't have to deal with such friction when working with structured content that offers clear visual affordances.
It's almost polemical to say, but the past decade's advancements in reactive JavaScript frameworks are perfectly suited for building excellent authoring tools—not for the convoluted pipeline of transpiling Markdown into an abstract syntax tree that then gets integrated into a JavaScript templating language to output HTML.
Block Content Deserves A Real Specification
Traditional WYSIWYG HTML editors are the wrong model. Modern block editors should interoperate with a defined, portable format. The editors mentioned above have sensible internal document models that can be transformed. Across the CMS landscape, JSON-based block formats are emerging, but many are still tied to HTML assumptions or overly concerned with character positions, and none are offered as a generic specification.
At Sanity.io, the early decision was that a block content format should never assume HTML as input or output, and that algorithms could handle text synchronization. The key insight was that block content and rich text should be deeply typed and queryable. This led to the open specification Portable Text. Its structure accommodates custom data structures as blocks and inline spans, and it is fully queryable with open-source languages like GROQ.
Portable Text isn't meant to be written or read in its raw form. It's designed to be generated by a user interface, manipulated by code, and serialized for any destination—including voice assistants. Treating block content as structured data means it becomes data, which can be queried and processed in ways that are far more difficult and error-prone with Markdown.
This opens up practical possibilities. For example, finding out which programming languages have appeared in code blocks across a blog is achievable with a short query. Building specialized tools and views on top of this data for content editors becomes trivial.
{
"style": "normal",
"_type": "block",
"children": [
{
"_type": "span",
"marks": ["a-key", "emphasis"],
"text": "some text"
}
],
"markDefs": [
{
"_key": "a-key",
"_type": "markType",
"extraData": "some data"
}
]
}
Example: Get a distinct list of all programming languages that you have code blocks of.
distinct(
*["code" in body[]._type]
.body[_type == "code"]
.language
)
// output
[
"text",
"javascript",
"json",
"html",
"markdown",
"sh",
"groq",
"jsx",
"bash",
"css",
"typescript",
"tsx",
"scss"
]Portable Text is also serializable, allowing recursive traversal with an API that exposes nodes via callback functions mapped to block types and marked-up spans. The project is approaching a 1.0 release, with the next step being an editor experience outside of Sanity Studio. As Markdown has taught us, design intent is crucial.
The alternative to Markdown doesn't have to be Portable Text specifically, but it does need to be portable text—and share its core characteristics. Other JSON-based block formats have emerged, but many carry "HTMLism" baggage. That convenience is understandable, given much content ends up on the web as HTML, but it limits portability and reuse. Even if you disregard this pitch for a Sanity product, the principle of structured content that allows fundamental movement between systems is sound. A stated goal for Portable Text is improved compatibility with Unified.js to ease travel between formats.
Markdown's Legacy And The Road Ahead
Markdown—in all its flavors and forks—isn't disappearing. Plain text files will always have a place in developers' notes, blogs, and digital gardens. Many rich text editors now support markdown-style shortcuts, and their absence in Google Docs is a common frustration. However, the next generation of creators and developers shouldn't be expected to subscribe to Markdown's conventions.
Markdown captured a culture of tinkerers who value text, markup, and automation. That creative energy should now be directed toward building better, more accessible block content editors and an ecosystem around specifications that are agnostic to HTML. Structured data formats may lack plain text ergonomics, but they are highly "tinkerable" and open to creative expression.
For developers and decision-makers, the choice of content storage format warrants careful consideration. If you're leaning toward Markdown, weigh these trade-offs:
Markdown is not great for developer experience in modern stacks:
- Parsing and validation can be a hassle, even with good tooling.
- Adopting CommonMark doesn't guarantee compatibility with all tooling or expectations.
- It's not suited for structured content; YAML frontmatter has its limits.
Markdown is not great for editorial experience:
- Most content creators would rather not learn syntax; their time is better spent elsewhere.
- Markdown systems are often brittle when syntax is entered incorrectly—and it will be.
- Building great collaborative experiences on top of Markdown is difficult.
Markdown is not great in the block content age, and shouldn't be forced into it. Block content needs to:
- Be untangled from HTMLisms and presentation agnostic.
- Accommodate structured content for use wherever it's needed.
- Have stable specification(s) to enable building upon.
- Support real-time collaborative systems.
Both those who challenge Markdown's prevalence and those who appreciate its simplicity share a common interest: how intent is transcribed into code. That's a meeting point. But it's time to examine emerging content formats that address modern needs, and ask how we can build systems that serve both editorial and developer experiences well.
Gratitude to Titus Wormer (@wooorm) for insightful feedback on an early draft, and for the work he and the Unified.js team do for the web community.
