Headless CMS for JAMstack: When It Actually Helps

JAMstack sites used to load content from markdown files in the repo. Then everyone "modernized" by bolting on a headless CMS — and half the time, the result is slower to build, harder to maintain, and the editors still hate the workflow. This post is the honest tradeoff: when a headless CMS earns its place on a JAMstack site, and when you should leave the markdown files alone.

TL;DR — A headless CMS helps a JAMstack site when non-developers edit content, when the same content goes to multiple frontends, or when content updates need to ship without a deploy. Skip it when the only editor is you, the site has fewer than ~30 pages, or every content change is paired with a code change. The middle ground (markdown + a small CMS for the blog only) often wins.

What "JAMstack + Headless CMS" Actually Means

JAMstack is a build pattern: a static site generator (Astro, Next.js static export, SvelteKit, Eleventy, Hugo) builds your site at deploy time. The output is HTML, CSS, JS — no runtime database. Fast, cheap, secure.

A headless CMS is content storage with an API. The site generator fetches content at build time (or runtime if you do ISR/SSR), then renders it.

The combination is supposed to give you:

• Editor-friendly content management (no Markdown in git)
• Multi-channel content (web + mobile + email from one source)
• Decoupled scaling (CMS team and frontend team move independently)

Sometimes it delivers. Sometimes it adds a second deploy step, a third bill, and a fourth team meeting.

When Headless CMS Actually Helps a JAMstack Site

Five scenarios where the combination pays off:

1. Non-developers edit content

This is the headline use case. If a marketing team, a content writer, or a non-technical client edits the site, asking them to write markdown in git is hostile. A CMS gives them a form, a rich-text editor, a preview button. That's the right interface for the job.

What "non-developer edits" means in practice:

• A marketing team that updates pricing page copy weekly
• A blog writer who publishes 2-3 posts a week
• A product team that swaps out feature descriptions per release
• An agency client who edits their own site between billable hours

If none of those describe your site, you don't need a CMS for this reason. The "but editors might want it later" argument is a tax you pay now for value you might never get.

2. The same content goes to multiple frontends

If a single content set powers a marketing site AND a mobile app AND an email template, the CMS-as-API model earns its place. You write once, multiple frontends fetch the same JSON. Updates propagate without copy-paste.

This is real for product companies with web + iOS + Android. It's rare for pure marketing sites.

3. Content updates need to ship without a deploy

A JAMstack site rebuilds when content changes. If your build takes 6 minutes and editors push 20 updates per day, that's 2 hours of deploys per day. Incremental Static Regeneration (Next.js) or on-demand revalidation can fix this — but only if your CMS knows when to trigger revalidation.

A real headless CMS gives you:

• Webhook on content change → triggers ISR/build
• Preview tokens so editors see drafts without a full rebuild
• Edit-in-place workflows that update without a deploy at all (server-rendered fragments)

If your site rebuilds in 30 seconds and editors push 3 updates a week, this matters less.

4. The site has structured content (not just a blog)

Markdown handles posts and pages fine. It breaks down when you have:

• A product catalog with 50 fields per item
• A team directory with photos, bios, social links, ordering
• An events page with structured RSVP, location, capacity
• Localized content across 5 languages

Markdown front matter can fake all of that, but the editor experience is terrible. A CMS with proper field types — relations, references, repeaters, asset pickers — is the right tool.

5. You need content workflows

Drafts, approvals, scheduling, version history. A CMS ships these. Markdown + git can fake some of them (PRs as approval workflow) but the editorial UX is wrong for non-developers.

If your content is published the moment it's written, you don't need this. If three people need to sign off before a post goes live, you do.

When You Should Skip Headless CMS

Four scenarios where staying on markdown wins:

1. The only editor is you

If the developer writing the code is also the only person writing the content, a CMS adds friction without solving anything. You edit a markdown file in your editor, commit, push. The site rebuilds. Done.

A CMS adds:

• Another login to remember
• Another bill to pay (or another server to maintain)
• A round-trip from CMS → API → build → deploy instead of edit → commit → deploy
• One more service that can break

If none of those costs are buying you anything, don't pay them.

2. The site has fewer than ~30 pages

Below 30 pages, the structural overhead of a CMS isn't worth it. You don't need a content model, you need 30 markdown files. Searching and editing is faster in your editor than in a web UI.

The exact number varies — a single-page marketing site needs no CMS, a 200-page docs site benefits even with one editor. But "small + static" is markdown territory.

3. Every content change is paired with a code change

If your content is so coupled to the code that every blog post comes with a new layout component, every product page has custom interactive widgets, every page is essentially bespoke — the CMS is fighting you. You'd be moving content out of git just to push it back in via a different channel.

This is fine. Some sites are essentially long-form code. Keep the markdown.

4. You can't afford the second service

A headless CMS is another piece of infrastructure. SaaS options (Contentful, Sanity, Storyblok) start at $15-50/mo and escalate fast. Self-hosted options (Strapi, Directus, UnfoldCMS) need a server. Either way, it's not free.

If your site generates no revenue or you're a side project that costs $0 today, adding a $50/mo dependency to make editing slightly nicer is a bad trade.

The Middle Ground: Markdown for Most, CMS for the Blog

Most JAMstack sites that "need a CMS" actually only need one for the blog. Static pages (home, about, pricing, features) change once a quarter — markdown is fine. Blog posts publish weekly — a CMS helps.

The pattern:

/content/
├── pages/              ← markdown, edited by devs
│   ├── home.md
│   ├── about.md
│   └── pricing.md
└── blog/               ← fetched from CMS at build time
    └── (populated by CMS API)

Your static site generator fetches /blog/ from the CMS API and renders alongside the markdown pages. Editors only touch the CMS for posts. Developers only touch markdown for the static pages.

This is the cheapest, fastest setup for 80% of marketing sites. It avoids the trap of moving everything into a CMS just because you added one.

If you're building on Next.js, the best CMS for Next.js page walks through this hybrid setup with code. Same pattern works on Astro and SvelteKit.

A Decision Checklist

Pick the path that matches your site:

The takeaway: there's no universal answer. Match the tool to the actual editing pattern, not to what the latest blog post recommends.

Which Headless CMS for JAMstack Specifically

If you've decided headless makes sense, the candidates fall into two camps:

SaaS (no server to run): Contentful, Sanity, Storyblok, Hygraph

• Pros: zero ops, fast to start, generous free tiers
• Cons: vendor lock-in, API rate limits, content lives on their servers, costs scale with usage

Self-hosted (own your stack): Strapi, Directus, Payload, UnfoldCMS

• Pros: own your data, no per-API-call fee, flexible schema
• Cons: server to maintain, you handle backups, you handle scaling

For JAMstack specifically, three traits matter:

1. Webhook on content change — so your site rebuilds without manual triggers
2. Preview API with auth tokens — so editors see drafts before publishing
3. Image transformation API — so the SSG can request right-sized images

Most modern CMSes ship all three. UnfoldCMS ships webhooks (incoming Stripe-style only — outgoing webhooks are not built yet), a small public read-only JSON API at /api/blog/posts, and Spatie Media Library conversions for image sizing. If outgoing webhooks for build triggers are critical to your workflow today, check headless CMS architecture explained for the wider tradeoffs.

For deeper comparisons, the complete guide to headless CMS in 2026 ranks the major options on these traits. The headless CMS vs traditional CMS post covers when the headless model itself is wrong for the job.

Common JAMstack + Headless Mistakes

Three patterns to avoid:

Mistake 1: Putting marketing copy in the CMS just because you can

Your home page hero copy isn't marketing department territory if marketing isn't editing it. If the dev team writes and tweaks home page copy in PR reviews, leave it in markdown. Moving it into the CMS adds friction without adding value.

Mistake 2: Treating the CMS like a database

A headless CMS isn't a real database. Don't store user accounts, orders, transactional data, or anything that mutates frequently. CMSes are optimized for editorial workflow, not OLTP. Use the right tool — Postgres for app data, CMS for content.

Mistake 3: Forgetting that builds cost time and money

Every content change triggers a build. Vercel, Netlify, Cloudflare Pages — they all meter build minutes. A site with 50 content updates per week and a 4-minute build burns 200 minutes/week. Over a month, that's expensive on hobby plans.

Mitigations:

• ISR or on-demand revalidation (Next.js, SvelteKit)
• Incremental builds (Astro 4+, Gatsby)
• Self-hosted runners (cheaper at scale, more setup)

If your CMS can trigger partial rebuilds, configure it. Don't rebuild the whole site for one blog post edit.

A Realistic Build Plan

If you're starting from scratch on a JAMstack site with the "CMS or not" question open, do this:

1. Build the first version with markdown. No CMS. Just files. Ship it.
2. Wait three months. Track who's editing what. Count edits per week.
3. If non-developers are editing: add a CMS for the section they edit. Keep the dev-only sections in markdown.
4. If only developers are editing: stay on markdown.

This avoids the trap of buying infrastructure you don't need. It also gives you real data — "marketing wants to edit pricing weekly" is different from "marketing might want to edit pricing eventually."

The "CMS-first" architecture is a tax most JAMstack sites don't need to pay on day one. Add it when the friction is real.

FAQ

Can I use a headless CMS with Astro?

Yes. Astro's content collections API can be replaced or supplemented with a CMS fetch. The best CMS for Astro page covers concrete patterns — fetch posts at build time, render to static HTML, deploy.

Does a headless CMS slow down my JAMstack site?

At runtime, no — the site is still static HTML. At build time, yes — fetching content from an API adds time vs reading from disk. Optimization: cache the API response, parallelize fetches, use incremental builds. The user-facing site stays fast.

What about SEO with a headless CMS on JAMstack?

SEO is the frontend's job, not the CMS's. As long as your SSG renders proper <title>, meta descriptions, and structured data, the CMS is invisible to Google. The headless CMS SEO post covers the details.

Should I use markdown or a CMS for a documentation site?

Documentation usually wants markdown. Devs write docs, devs commit docs, devs review docs. The best CMS for documentation sites page covers when a CMS makes sense for docs — usually only when non-dev technical writers contribute.

Can I migrate from markdown to a headless CMS later?

Yes. Most CMSes have markdown import tools. The migration is tedious (writing a script to parse front matter + body and POST to the CMS API) but not technically hard. Save it for when you actually need the CMS.

Does UnfoldCMS work with JAMstack frameworks?

Yes — UnfoldCMS exposes a read-only JSON API at /api/blog/posts and /api/blog/posts/{slug}. Fetch from your Astro/Next.js/SvelteKit build, render statically, deploy. Note: outgoing webhooks aren't shipped yet, so for build triggers you'd poll or use a manual revalidation endpoint.

What to Do Next

If you're already on markdown and it's working, don't fix what isn't broken. The "everyone is moving to headless CMS" narrative is half-true — many sites are, but many shouldn't be.

If you're hitting real editor friction, pick a CMS that matches your scale. Self-hosted if you want to own the data. SaaS if you want zero ops. Either way, start with the blog only, not the whole site.

If you want to compare specific options, the 10 best WordPress alternatives in 2026 post covers most modern headless CMSes side-by-side. Pricing is on the site if you want to compare TCO.

Related: The Complete Guide to Headless CMS in 2026, Headless CMS vs Traditional CMS, When NOT to Use a Headless CMS.

Methodology

The framing in this post (when headless CMS earns its place vs when markdown wins) draws on conversations across r/webdev, r/nextjs, and the Astro Discord during April-May 2026. Specific tradeoffs around incremental builds verified against Vercel Next.js docs and Astro 4 release notes. UnfoldCMS feature claims (read-only API, no outgoing webhooks yet) verified against the source as of May 24, 2026.