The decision I made for this site was to ship content as MDX files committed to the same Git repository as the rest of the code, built statically with Next.js, deployed via Vercel. No headless CMS, no WordPress, no Contentful, no Sanity. Just MDX files and a registry JSON.
That is a weird choice for a content-heavy site in 2026, because the default advice is to use a headless CMS for content velocity and editor friendliness. This is the decision log explaining why I chose MDX, what I gave up by choosing it, and where the tradeoff would flip for a different team.
The decision criteria
Five criteria shaped the decision.
Author count. This is a one-author site. A CMS designed for teams of 5-20 editors is optimizing for a problem the site does not have.
Technical fluency of authors. The author is a developer. Editing MDX directly is not a friction for a developer-author. For a team with non-technical writers, it would be.
Rendering requirements. The site ships interactive demos alongside prose. Every article has a custom React component embedded mid-content. That pattern works natively in MDX and awkwardly in any CMS that was designed for pure text.
Version control requirements. I wanted every content change to go through a pull request, be reviewable in diff form, and be rollback-able via Git. Headless CMSes offer versioning but not the same shape.
Runtime cost. MDX compiled statically at build time has zero runtime cost at render. No database, no API call, no CMS hosting bill.
Four of the five criteria pointed to MDX. One (non-technical editing) pointed away. I weighted the four heavier than the one and committed.
What I gave up by choosing MDX
Three real costs.
Non-technical authoring is hard. If I wanted to hire a copywriter who does not know Git, they could not realistically edit content directly. They would need to hand me Word docs and I would need to translate. For a solo site this is fine. For a team with non-technical writers it is a blocker.
Preview requires a full build. In a headless CMS, the preview is a live API fetch. In MDX, the preview is a local build of the site. The build is fast with Next.js and Turbopack, but it is still slower than a live fetch. For high-frequency editing this friction compounds.
Rich media workflows are DIY. A CMS typically handles image resizing, video hosting, and asset CDN integration out of the box. In the MDX setup I run, I wrote a Node script that optimizes hero images and a convention for where they live. That script is mine to maintain. A CMS would have done it for me.
None of these costs killed the decision, but they are real. A team where any of them is a blocker should not use MDX as their primary CMS.
What I gained
Four genuine wins.
Git as the audit trail. Every content change is a commit. Every commit has a message explaining why. Every branch is a review context. The audit trail is native and free. This is load-bearing for the programmatic SEO workflow where I ship multiple articles per day; I need to be able to see what changed, when, and why.
MDX enables inline interactive demos. Every article in this cluster has a custom React demo component embedded mid-prose. That pattern is native to MDX and requires significant glue in any CMS that was designed for pure text. On this site, the demo is a first-class citizen, not a widget embed.
Build-time optimization is native. Images get optimized at build time via Next.js Image. Links get validated at build time. The type system catches frontmatter typos at build time. The whole build pipeline runs through TypeScript strict mode and Turbopack. That level of integration would require significant custom work with a CMS.
Zero runtime cost. No CMS subscription, no database, no API latency. The build step is the only cost, and it is measurable in seconds. For a site that might eventually ship thousands of articles, the runtime economics matter.
The tradeoff map
Where the decision should flip:
Author count above 5. At a team of 5+ content editors, the non-technical editing cost of MDX compounds badly. Use a headless CMS with good role management (Sanity, Contentful, Payload).
Non-technical authors. If any of the authors cannot work in Git, MDX is a non-starter. A headless CMS with a friendly editor UI is the right call.
Content that needs localization workflows. Translations, language variants, country-specific content. MDX can do it but badly. A CMS with a translation workflow is much better.
Content that changes more frequently than the code. If the content refresh rate is measured in edits per hour and the code refresh rate is measured in deploys per week, decoupling them via a CMS is the right instinct. For this site, both are measured in commits per day, so the coupling is free.
The reverse is also true. A headless CMS for a one-person team writing 2-5 articles per week is usually overkill. The overhead of learning the CMS, paying for it, and integrating it outweighs the editor friendliness benefit.
What the MDX stack looks like on this site
The pieces:
src/content/writing/*.mdxare the article filessrc/content/writing/_registry.jsonis the article registry with metadata, status, and interlinking trackingmdx-components.tsxis the global component registration for MDX- Each article's demo lives at
src/components/writing/demos/<slug>-demo.tsx src/lib/writing.tshandles article loading, frontmatter parsing, sorting, and filtering- Next.js App Router handles the routing and rendering
- Tailwind v4 handles the typography and layout tokens
- Vercel handles build and deploy
That is the whole stack. The total lines of custom infrastructure code are in the low hundreds. A headless CMS integration would be more.
“The MDX-in-Git pattern has the cost profile of a 2010 static blog with the output quality of a 2026 production site.
”
Where this decision would break
Two scenarios that would push me to migrate.
Growing past 5 editors. If I hired 2-3 writers who did not know Git, I would migrate to a headless CMS within 6 months. The friction compounds too fast.
Content volume past a few thousand articles. MDX builds get slow at some scale. The Next.js build on this site runs in under 2 minutes today. If it crossed 10 minutes, I would look at ISR with a headless CMS backend to defer the build cost. That point is probably several thousand articles away.
Neither scenario is likely in the next 12 months. Until one of them shows up, MDX stays.
Where this fits
This decision log sits alongside the cluster hub as the infrastructure piece. Content velocity with AI agents covers how the MDX stack supports multi-article-per-day shipping. Core Web Vitals and SEO in 2026 covers why the static-build approach keeps CWV in the green.
For the broader stack thinking, the creative-tech operator playbook covers the operator shape that makes MDX viable as a content system for one person.
If you want to evaluate whether your current content stack is the right fit for your team, the DTC stack audit covers content infrastructure alongside tracking and SEO. Full product ladder at /products.
Sources and further reading
- MDX.js documentation, current version
- Next.js App Router MDX integration guide
- Sanity, Contentful, Payload CMS comparison write-ups, 2024-2025