The Headless CMS Trap | Static Signal

You finally ripped out WordPress. No more plugin roulette. No more database backups at 2am. No more patching security holes in a contact form plugin you installed three years ago.

So you picked a headless CMS. Contentful, maybe. Or Sanity. Or Strapi. The pitch was clean: structured content via API, front-end freedom, modern developer experience.

Six months later you’re paying $300/month for a content API, your editors are confused by a schema builder that looks like a database admin tool, and migrating away would mean rewriting every content query in your app.

You didn’t escape the trap. You walked into a nicer one.

The Promise vs. the Reality

The headless CMS pitch is genuinely compelling. Decouple your content from your presentation layer. Use any front-end framework. Deliver content to web, mobile, kiosks, whatever. It’s the right architecture for a real set of problems.

The issue is that most teams adopting headless CMS platforms don’t have those problems. They have a blog. Maybe a marketing site with some landing pages. Maybe a docs site. They chose a headless CMS because it felt like the modern thing to do — and now they’re paying the complexity tax on infrastructure they didn’t need.

The Costs Nobody Talks About

Vendor lock-in is real

Every headless CMS has its own content model, its own API shape, its own SDK, its own way of handling relationships between content types. Contentful’s content model is nothing like Sanity’s GROQ-based approach, which is nothing like Strapi’s REST/GraphQL setup.

Once you’ve built 40 pages of content with custom types, references, and rich text fields in Contentful, the cost of switching to Sanity isn’t “swap the API calls.” It’s a full content migration, schema redesign, and query rewrite. That’s vendor lock-in with better marketing.

Pricing scales against you

Most headless CMS platforms price by seats, content entries, API calls, or some combination. That’s fine at launch. It’s less fine when your marketing team grows, your content library expands, and suddenly you’re on the $500/month plan because you crossed an entry threshold.

Contentful’s free tier caps at 5 users and 25K records. Sanity’s free tier limits API requests. These aren’t unreasonable limits, but they create a ratchet: the more content you produce, the more you pay, and the harder it is to leave because your migration cost grows with your content volume.

Your editors probably hate it

Here’s the part that doesn’t come up in architecture discussions: most headless CMS editing interfaces are built for developers, not writers. Sanity Studio is powerful but intimidating. Contentful’s editor works fine until you need rich text with embedded components, at which point you’re debugging JSON rendering pipelines. Strapi’s admin panel feels like a database GUI with a coat of paint.

Compare this to the editing experience in WordPress — for all its problems, the block editor is genuinely good for non-technical users. Most headless CMS platforms traded editor usability for developer flexibility without acknowledging the tradeoff.

When a Headless CMS Actually Makes Sense

This isn’t a “headless CMS bad” post. There are real use cases where the architecture earns its complexity:

Multi-channel content delivery. If you genuinely need to serve the same content to a website, a mobile app, and a digital signage system, a content API is the right tool. Most teams don’t have this requirement, but the ones that do really need it.

Large editorial teams with structured workflows. If you have 10+ editors, content approval pipelines, localization across multiple languages, and role-based access controls, a headless CMS provides real value. A marketing team at a mid-size SaaS company managing 500 pages across 4 languages — that’s a legitimate use case.

Dynamic content that changes frequently. Product catalogs, event listings, real-time pricing — content that updates multiple times a day benefits from a CMS with webhook-triggered rebuilds or ISR. A rebuild-on-commit workflow doesn’t scale here.

Regulated industries with audit requirements. If you need a full audit trail of every content change, role-based publishing permissions, and scheduled content with approval gates, a headless CMS gives you that out of the box.

When You Should Just Use Markdown

For everything else — and this is most projects — markdown files in a Git repo are simpler, faster, and free.

A developer blog? Markdown. An agency portfolio? Markdown. A startup landing page with a blog? Markdown. A documentation site? Markdown. A small business site where a developer manages the content? Markdown.

Here’s what you get:

Zero cost. No SaaS subscription. No API limits. No seat-based pricing.
Zero lock-in. Markdown is a format, not a platform. Move it anywhere.
Version control for free. Every content change is a Git commit with a diff, a timestamp, and an author.
AI-native workflow. Any AI agent can read and write markdown files. No API credentials, no SDK, no schema to learn. This is a bigger deal than most people realize — your content pipeline becomes automatable with zero integration work.
Performance is the default. Content is read at build time. No API calls at runtime. No waterfall of CMS requests slowing down your page loads.

The objection is always the same: “But what about non-technical editors?” Fair point. But before you spin up a $300/month Contentful instance to solve that problem, consider the alternatives:

Tina CMS gives you a visual editing interface on top of markdown files in your repo. Your editors get a WYSIWYG experience. Your content stays in Git. No vendor lock-in.

Keystatic does something similar — a local-first CMS that writes to your file system. Content stays portable.

Obsidian Publish or a simple markdown editor with a Git integration gets you surprisingly far for basic content workflows.

These aren’t perfect solutions. But they solve the editing problem without introducing the architectural complexity and ongoing costs of a full headless CMS.

The Decision Framework

Before choosing a headless CMS, ask these three questions:

1. Do I need to serve this content to more than one platform? If the answer is only a website, you probably don’t need a content API.

2. Do I have non-technical editors who need to update content without developer involvement? If yes, you need an editing interface — but that doesn’t automatically mean you need Contentful. A Git-backed visual editor might be enough.

3. Am I choosing this because it solves a real problem, or because it feels like the modern thing to do? Be honest. “Our architecture diagram looks cleaner with a headless CMS” is not a reason to add a SaaS dependency to your stack.

If you answered “just a website,” “developers manage content,” and “it feels modern” — you’re about to walk into the trap. Use markdown. Ship faster. Save the money.

The Pattern I Keep Seeing

A team migrates off WordPress. Good decision. They evaluate headless CMS options and pick one that handles their current content volume on the free tier. They build the site, launch it, and everything’s fine.

Eighteen months later: the content library has grown, they’ve hit a pricing tier, the original developer who set up the content model has left, and the new developer is trying to understand a schema with 47 content types and a web of references that nobody documented. The editors are asking why they can’t just type in a normal text box. The CFO is asking why the company is paying $6,000/year for what amounts to a blog.

This is the headless CMS trap. It’s not that the technology is bad. It’s that the technology is designed for a scale and complexity that most projects never reach — and by the time you realize that, you’re locked in.

Keep it simple. Use markdown until you can’t. You’ll know when you actually need the upgrade — and when that day comes, you’ll make the decision with real requirements instead of hypothetical ones.

- Static Signal is published by Neuron Web Development.