MDX is a better CMS than your CMS (for sites that change quarterly)

Most marketing-site projects start with the same default: pick a headless CMS — Sanity, Contentful, Payload — and wire it up. For a meaningful slice of the sites we build, that default is wrong. The right answer is MDX in the repo, edited the same way the rest of the codebase is edited: through a pull request.

The hidden cost of a CMS

A headless CMS is not free, and the cost isn't just the monthly bill. It's the integration surface — schema migrations, preview environments, draft states, rich-text rendering pipelines, image CDN wiring, deploy hooks. It's the second login the client has to remember. It's the "the site looks broken, did Sanity have an outage?" debugging path. And it's the part of the stack the client cannot move when they want to leave the agency that set it up.

For a site with high editorial volume — a content marketing operation, a publication, a knowledge base — all of that overhead pays for itself many times over. For a six-page HVAC site that updates its FAQ twice a year, none of it does.

What MDX gives you that's comparable

MDX is Markdown with JSX. A blog post is a .mdx file in the repo. Frontmatter is the metadata: title, summary, published date, tags. The body is Markdown for prose plus inline JSX for anything custom — a callout, a chart, an embed. Versioned in git, reviewable in pull requests, deployable through the same pipeline as code.

For Trinity Climate Control, that's the entire blog and FAQ system. No CMS, no preview environment, no second account. Trinity edits content the same way the developer does. They get git history of every change for free.

The honest objection: non-technical editors

The objection lands hardest when the client's editor is non-technical. They don't know git; they want to log in somewhere and click "edit." That's a real concern, and for clients whose marketing team includes a content writer who needs that workflow, MDX is the wrong choice.

But for clients where the editor is the founder or the developer or the operator — which describes most small-business sites — "edit a Markdown file and merge a pull request" is not a higher friction than "log in to Sanity, find the entry, click into the rich-text editor, save, publish, hope the deploy fires." It's arguably lower.

When we still pick a CMS

We'll still pick a CMS when:

• The editorial team is > 1 non-technical writer working in parallel.
• The publishing cadence is multiple posts per week.
• The content needs scheduled publishing, draft review, or a real workflow.
• Marketing needs to localize content into multiple languages with translator workflows.
• There's a real CMS-shaped problem, not a "the agency suggested it" problem.

For most of the sites we ship — local-services, personal brands, small e-commerce, marketing landers — none of these conditions hold. The CMS would be there to make us look more sophisticated, not to make the client's life better. We'd rather skip it.

The TypeScript-objects variant

For some sites, even MDX is more than the editorial cadence justifies. Cody Sirk's blog is a TypeScript array of post objects, with TSX bodies. Same authoring power as MDX, zero MDX build pipeline, full type safety on metadata. It's the right tool for a working musician who publishes a few posts a quarter and wants the site to keep working in five years without a build-tool migration.

Pick the simplest thing that fits the editorial cadence. The default of "reach for the CMS first" should be earned, not assumed.