MD vs MDX: The Decision Most AI-Agent Repos Get Wrong

Every AI coding tool on the market reads .md files. Not one of them needs .mdx. That is not a coincidence. It is a design decision that reveals something fundamental about what these two formats actually are.

Markdown and MDX are often discussed as if they were competing formats. They are not. They solve different problems at different layers of the content stack. But the AI era has made the distinction urgent, because choosing the wrong default for an agent-consumed repository introduces parsing complexity, build dependencies, and framework coupling that no agent can reason about.

This article covers where each format came from, why both are surging in 2026, and the decision rule that keeps the knowledge layer clean.

How Markdown Became the Default

Markdown was created by John Gruber and Aaron Swartz in 2004. Gruber published the original specification on Daring Fireball on March 19 of that year. Swartz was the sole beta tester and wrote html2text, a tool for converting HTML back into Markdown.

The design goal was specific: create a plain-text format that remains readable before it is rendered. A heading uses a hash character because # Title already looks like a title in a plain-text email. Bold uses asterisks because *word* was a common convention in newsgroups. The philosophy was simple: if the unrendered source looks wrong, the syntax is wrong.

Here is what a deploy runbook looks like in plain Markdown:

# Deploy Runbook

## Pre-flight checks
- [ ] All tests pass on `main`
- [ ] No open P0 incidents

## Steps
1. Tag the release: `git tag v2.4.1`
2. Push: `git push origin v2.4.1`
3. Monitor: check Grafana for 15 minutes

No build step. No imports. No framework. Any text editor opens it, any CI pipeline parses it, any human reads it cold. That document is complete at rest.

Markdown won because nothing simpler appeared to replace it. Zero tooling required. Version-control friendly, with clean line-by-line diffs. The learning curve is measured in minutes. GitHub made it universal by choosing .md for README files, wikis, issues, and pull requests. By the time CommonMark standardized the specification in 2014 and GitHub adopted CommonMark-based GFM in 2017, Markdown was already the lingua franca of developer documentation.

A 2025 study analyzing prompt storage practices across GitHub repositories found that Markdown is the most widely adopted file format, used by 72.8% of the repositories examined (arXiv, 2025). That number will not shrink.

Why MDX Exists (and Why It Took Off)

MDX was born from a real limitation. By 2017, documentation teams using Markdown were hitting a wall: they needed interactive examples, tabbed content, live code playgrounds, and reusable callout components. HTML-in-Markdown was fragile. Custom remark and rehype plugins were brittle and hard to maintain. There was no clean way to keep Markdown's authoring ergonomics while embedding component logic.

Guillermo Rauch, John Otander, Tim Neutkens, and several collaborators created MDX to solve exactly that problem. Otander wrote most of the code for the first alpha and later stable v1 release. The tagline, "Markdown for the component era," was precise: MDX lets authors import and embed JSX components directly in content.

Here is the same deploy runbook in MDX:

import { Callout } from '../components/Callout'
import { Steps } from '../components/Steps'

# Deploy Runbook

<Callout type="warning">
  All tests must pass before proceeding.
</Callout>

<Steps>
  <Step title="Tag the release">
    Run `git tag v2.4.1` from the main branch.
  </Step>
  <Step title="Push">
    Run `git push origin v2.4.1`.
  </Step>
</Steps>

Richer presentation. Better reuse. But now the document depends on a component library, a build pipeline, and a framework runtime. That file is incomplete until built.

MDX became popular because the audience was already there. React's dominance in frontend development (2018-2022) created millions of developers who thought in components. When Meta's Docusaurus v2 shipped in 2020 with MDX as the default content format, it became the path of least resistance for docs sites. Nextra did the same for Next.js. Storybook adopted it for component documentation. Today, @mdx-js/mdx pulls between 9.8 and 12.7 million npm downloads per month, and Docusaurus has over 64,000 GitHub stars.

MDX is still popular because the docs-as-code movement wants content that lives alongside the application, uses the same component library, and deploys through the same CI pipeline. MDX is the only format that does all three without workarounds.

The AI-Era Resurgence

Both formats are experiencing a major resurgence in 2026, but for entirely different reasons.

Markdown's New Role: The Agent Protocol Layer

Every major AI coding tool chose .md as its instruction format. Not .yaml. Not .json. Not .mdx. Plain Markdown.

# Project Instructions

## Build & Test
- Run tests: `npm test`
- Lint: `npm run lint`

## Architecture
- Backend: Express + PostgreSQL
- Auth: JWT via jose library
- Never modify migration files directly

Claude Code reads CLAUDE.md. GitHub Copilot reads copilot-instructions.md. OpenAI's Codex reads AGENTS.md. Cursor uses .mdc files in a rules directory, but the content is Markdown. Windsurf, Gemini CLI, Aider, Zed: all Markdown.

The convergence is not accidental. In August 2025, OpenAI released AGENTS.md as an open specification through the Linux Foundation's Agentic AI Foundation (AAIF). By May 2026, the AAIF had grown to over 170 member organizations, and AGENTS.md had been adopted by more than 60,000 open-source repositories (Codex Knowledge Base, 2026).

The research backs the format choice. Developer-written Markdown instruction files improve agent task success rates by approximately 4% and reduce agent-generated bugs by 35 to 55% (DeployHQ, 2026). The same study found that LLM-generated instruction files actually decrease success rates and increase inference cost by over 20%. The format works. The content quality matters.

Markdown went from "developer documentation format" to the protocol layer between humans and AI agents. LLMs are trained on billions of .md files from GitHub. RAG pipelines chunk and index Markdown natively. Agents read, write, and diff it as their primary content interface. The format that Gruber designed in 2004 to be readable without rendering turned out to be exactly what machines needed too.

MDX's Resurgence: AI-Powered Documentation

MDX is surging for a different reason. The docs-as-code movement accelerated as AI made it faster to write and maintain documentation. Postman's 2025 developer survey found that 41% of developers now use AI to generate API documentation (Infrasity, 2025). More documentation being written means more demand for interactive, component-driven documentation experiences. MDX is the format that delivers those experiences.

AI-powered documentation generators, interactive tutorials with live code playgrounds, and component-driven docs that AI tools can compose and update: all of these lean on MDX's ability to mix prose with executable components.

The Distinction That Matters

The simplest way to understand the difference: Markdown is a storage format. MDX is an execution format.

A Markdown file is complete at rest. Open it in any text editor, and the content is there. No imports to resolve, no components to render, no build step to run. The file stores knowledge in a form that is durable, portable, and machine-readable without transformation.

An MDX file is incomplete at rest. It contains import statements that reference external modules, JSX expressions that require a runtime, and component calls that depend on a framework. Until the build pipeline resolves all of those dependencies, the file is not fully legible. It is source code for a document, not the document itself.

That distinction explains every tradeoff between the two formats. Storage formats optimize for durability, portability, and low friction. Execution formats optimize for expressiveness, reuse, and presentation control. Neither is better in the abstract. But conflating the two, using an execution format where a storage format belongs, is where the cost shows up.

Why AI-Agent Repos Default to .md

AI agent workflows need content that is deterministic, easy to chunk, easy to diff, and parseable without special rendering assumptions. Plain Markdown fits every one of those requirements.

Consider what an agent does with a project instruction file: it reads the content as a single text stream, extracts structured information (commands, constraints, architecture notes), and applies that context to code generation tasks. The agent does not render components. It does not resolve imports. It does not run a build pipeline. Any syntax that requires those steps is noise.

my-agent-repo/
  CLAUDE.md              # .md - agent instructions
  AGENTS.md              # .md - cross-tool agent config
  docs/
    architecture.md      # .md - system design notes
    api-reference.md     # .md - endpoint specs
    runbooks/
      deploy.md          # .md - operational procedures
  website/
    docs/
      getting-started.mdx   # .mdx - interactive tutorial
      components.mdx         # .mdx - live component demos

The pattern is consistent: .md for the knowledge layer, .mdx for the presentation layer. They coexist in the same repository, but they serve different consumers. The knowledge layer serves agents, CI pipelines, and humans reading raw files. The presentation layer serves a rendered documentation website.

When teams use MDX for agent-consumed files, three things break. First, agents encounter import statements they cannot resolve, which either cause parse errors or get included as noise in the context window. Second, JSX components expand the token count without adding information the agent can use. Third, the files become coupled to a specific framework version, which means updating the docs site can break the agent instructions.

Where MDX Earns Its Place

MDX is the right choice when the document must do more than speak. If the content needs to show component examples, interactive widgets, live code, design-system variations, or tabbed content that stays consistent across dozens of pages, MDX reduces duplication and improves the reader experience.

import { Playground } from '../components/Playground'

## Authentication

Pass your API key in the `Authorization` header:

<Playground
  method="POST"
  endpoint="/api/v1/auth"
  body={{ apiKey: 'your-key-here' }}
/>

Try changing the API key above to see the error response.

That is a documentation experience that plain Markdown cannot deliver. The reader interacts with a live API endpoint inside the documentation page. No amount of code fencing or HTML embedding gives you that in .md.

MDX belongs in documentation sites (Docusaurus, Nextra, Starlight), component catalogs (Storybook), design system documentation, interactive API references, and educational content where the reader learns by manipulating live examples. These are all contexts where the document is part of the user interface, not just a reference file.

The Decision Rule

Default to .md unless you have a specific, recurring presentation need that Markdown cannot handle cleanly. If the document must stay portable, easy to parse, and friendly to both humans and agents, Markdown is the safer choice. If the document needs reusable components, interactive examples, or rich documentation-site behavior, MDX earns its place.

For AI-agent repositories, the practical rule is: .md for prompts, instructions, repo maps, policies, specs, and runbooks. .mdx for the parts of the system that are meant to be rendered into a richer user experience. That separation keeps the knowledge layer clean and the presentation layer expressive.

Markdown was designed in 2004 to be readable without rendering. Twenty-two years later, that same property is the reason every AI agent on the market reads it natively. MDX was designed in 2018 to make documents participate in component systems. Both formats are more relevant in 2026 than they have ever been.

The mistake is not choosing one over the other. The mistake is using an execution format where a storage format belongs. If an AI agent will ever read the file, it should be .md. The moment you need a build step to make a document legible, you have stopped writing documentation and started writing software.

Sources

1. arXiv (2025) - "Understanding Prompt Management in GitHub Repositories: A Call for Best Practices." Markdown used by 72.8% of analyzed repositories for prompt storage. arxiv.org
2. Linux Foundation AAIF / Codex Knowledge Base (2026) - AGENTS.md adopted by 60,000+ open-source repositories; 170+ member organizations. Developer-written instruction files improve agent task success by ~4% and reduce bugs by 35-55%. codex.danielvaughan.com
3. Postman (2025) - 41% of developers now use AI to generate API documentation. infrasity.com
4. DeployHQ (2026) - Comprehensive guide to CLAUDE.md, AGENTS.md, and AI coding tool configuration files. deployhq.com
5. npm (2026) - @mdx-js/mdx package: 9.8-12.7M monthly downloads. npmjs.com

Working through the challenges in this post? I help engineering leaders and CTOs navigate complex technical decisions and scale high-performing teams. Schedule a consultation →