Where Content Should Live: Markdown, a Headless CMS, or Both

Early in 2020 I wrote two posts that disagreed with each other. In the first, I’d moved my blog from Sanity, a customisable headless CMS, back to plain Markdown files, because I’d spent more time customising the CMS than writing. Two months later I wrote about how much I loved Sanity because I could fix a typo from my phone on the train.

Both posts were right. They were answering different questions.

The questions that actually decide it

Who writes? If it’s developers, Markdown in git is hard to beat: diffs, reviews, branches, no extra service. If it’s editors, marketers or translators, they need a proper editing interface, previews, roles and workflows. That’s what a headless CMS is for.

How often, and from where? My 2020 self wanted to write on commutes, from his phone. A hosted CMS made that easy; Markdown made it awkward. Since then, editing Markdown from a phone has become easy (a notes app or GitHub’s web editor), and that changed my answer for a personal site.

How structured is the content? A blog post is a document. A product catalogue across many markets is a graph of typed content with references between items. The more structured and reused the content, the more a CMS with a real content model earns its keep.

What I learned at scale

Later in 2020, at Elanco, I built a tool to move whole sites from one headless CMS to another (A Resumable CMS Migration Tool). Hundreds of items per site, images, videos and references between them. That job taught me the lessons the blog posts couldn’t:

• The content model is the real asset. Pages are just views. If the model is clean, you can change CMS, front end or both.
• Migrations are mostly about references and media, not text. Plan for links between items and for large binary assets.
• Make it resumable. Long migrations fail halfway; batching and checkpoints mean you restart from where you stopped (Resumable Batch Migrations).
• Lock-in hides in rich text. Every CMS stores formatted text differently, and that’s the hardest part to convert.

Where I landed for this site

This garden is Markdown, but not hand-maintained Markdown. I write in my private notes, a nightly process distils what’s worth keeping, and a publishing step turns selected notes into typed Markdown files with frontmatter (How I Take Notes: Capture, Distil, Resurface). Astro’s content collections validate the structure at build time. In effect, my notes are the CMS and git is the publishing workflow.

My rule of thumb now

• Developers writing, low volume: Markdown or MDX in the repo.
• Non-developers writing, or structured content reused across channels: a headless CMS with a deliberate content model.
• Both: keep the content model portable, so moving between them is a migration, not a rewrite.

And the line from my 2020 post that I still agree with: use the tools that fit how you actually work. Any second of friction between an idea and publishing it is a second for the motivation to drift.

---

Originally written in 2020 → Markdown vs Headless CMS and A CMS I can use on my phone