Migrating content into a headless CMS
A headless CMS stores content as structured data and renders nothing. That changes what a migration has to produce: not pages that look right, but a model everything downstream can be built from.
The destination model is designed, not discovered
In a conventional CMS the content model and the pages it produces are close together, so an imperfect model can be worked around in a template. A headless CMS has no templates — every consumer, whether a website, an app or a search index, builds on the model directly. A decision made casually about how content is typed becomes a constraint on every surface, and it is much harder to change once several consumers depend on it.
- Content has to serve a website and at least one other surface
- The current CMS is being replaced and the content has to move
- Content lives in several systems and needs one home
- A headless CMS has been chosen and the content model has not been designed
- The current model mixes content with presentation — layouts, styling, page furniture
- Editors' experience is a live constraint and the current system is the reason
- Content is duplicated across systems and the copies disagree
- A previous migration produced a model nobody can extend
The people who usually bring us this problem
A team moving content to a headless CMS
The destination is chosen and the modelling is the work, and you want it right before consumers depend on it.
A team whose content serves more than one surface
The same content has to reach a site, an app or another product, and the current model was built for one of them.
Someone consolidating content from several systems
There is more than one source and the destination has to reconcile them rather than concatenate them.
What this costs while it goes unfixed
Engineering faults are rarely confined to the engineering layer. These are the commercial consequences we see most often.
There is no template to absorb a modelling mistake
In a rendered CMS a confusing model can be hidden in the theme. In a headless CMS every consumer reads the model directly, so a decision about typing, nesting or reuse propagates into every surface and every future integration. The model is the product, and it is being designed whether or not anyone treats it that way.
Presentation often has to be removed during migration
Conventional content frequently embeds layout: styled blocks, positioning, typography, page furniture. A headless model carries meaning and lets each surface render it, so part of the migration is deciding what in the existing content is meaning and what was presentation. This is the step that is consistently underestimated, because it requires judgement rather than mapping.
References have to survive
Relationships between content — a page to its components, an article to its author and its topics, a product to its category — are the reason to use a structured model at all. A migration that moves the records but flattens the relationships has moved the text and lost the structure.
Editors are moving into a different way of working
A headless CMS shows content as fields rather than as a page. For some editorial teams that is a clearer model of what they are producing; for others it is a loss of a preview they relied on. Either way it is a change in the working day, and treating it as a technical detail is how a migration gets judged as a downgrade.
Capabilities
Each of these is work we carry out, not an area we advise on.
Audit of the existing content before modelling
What actually exists, in what shapes, and how consistently. This is the step that establishes whether the current model is one model or several, which is common after earlier migrations and changes the scope of everything that follows.
Destination model design
Content types, fields, references and reusable components, designed against how the content is used rather than against how it was stored. Done with the people who publish, because the model determines what they can produce.
Separating meaning from presentation
Deciding, item by item, what in the existing content carries meaning and what encodes how it looked. This is the judgement at the centre of a headless migration, and it is why the work cannot be reduced to a field mapping.
Field mapping with an explicit no-destination list
Every source field to a destination field, and a written list of what has nowhere to go. The list forces a decision — a new field, a conversion, or a deliberate omission — rather than permitting content to disappear quietly.
References and relationships
Moving the relationships between content, not only the records. This is where a structured model earns its cost, and it is the part a naive migration loses while reporting a correct record count.
Media migration and reference rewriting
Assets moved to the new system with every reference to them rewritten, including references inside rich text. Content managed in a headless CMS records its own asset references, so a migration that moves files without rewriting everywhere they are pointed at produces a structured site with no images.
Multi-source reconciliation
Where content lives in more than one system, establishing which source is authoritative per content type and reconciling rather than concatenating. Two copies of the same content produced by two systems will disagree, and the migration is where that gets decided rather than discovered.
Editorial workflow and preview design
What the editorial experience is in the destination, including preview: what an editor sees before publishing, and how the workflow supports review, scheduling and correction. Designed with the editorial team, since it determines whether the migration is experienced as an improvement.
URL preservation and redirect mapping
A complete inventory of existing addresses and a mapping onto the new content, activated with the cutover. Content moving between systems changes address unless it is deliberately preserved, and the search consequence is the largest risk in the project.
Engineering methodology
The sequence is deliberate. The order is usually what determines whether the work holds or has to be repeated.
Inventory and model before migrating anything
What exists, then what it should become. Migrating first and modelling afterwards produces a destination that reproduces the previous system's accidents — which is often the thing the previous system was being left for.
Separate meaning from presentation as its own step
It is the judgement a headless migration turns on and it cannot be automated: a field mapping tool will happily carry styling into a model that should not hold it. Doing it explicitly, with the editorial team, is what makes the resulting model durable.
Design the model with its consumers present
Every surface that will read the content has requirements on the model. Designing without them produces a model that suits the first consumer and has to be changed when the second arrives — which is the specific failure that makes a headless migration expensive later.
Map fields explicitly and record the exceptions
A written mapping, plus the list of content with no destination. The exceptions are where judgement is required, and they are precisely what a migration without a written mapping loses.
Migrate in passes and verify relationships, not just records
Content, then media, then the references that depend on both. Verification counts records per type and inspects the structure, because a correct number of entries with flattened relationships is a failed migration that reports success.
Rehearse and review the editorial experience
The destination model is exercised by the people who will publish in it, on real content, before the cutover. Model changes after several consumers depend on them are expensive, and this is the cheap moment to find them.
Preserve addresses and measure the result
Inventory, map, activate with the cutover, then track crawl, indexation and impressions against a baseline. The same discipline as any migration, and the discipline that most distinguishes a headless migration that goes well.
What an engagement produces
Documentation is a deliverable, not an afterthought. On most of these engagements a large part of the value is a defect report precise enough for another team to act on.
Model design
- Inventory of existing content, including inconsistencies and earlier structures
- Content types, fields, references and reusable components for the destination
- What in the existing content is meaning and what was presentation
- Field mapping, with an explicit list of content that has no destination
- Which source is authoritative where content exists in more than one system
- Editorial workflow and preview design, agreed with the people who publish
Migration
- Content and media migrated in verified passes
- Relationships moved as structure, not flattened
- Every asset reference rewritten, including inside rich text
- Verification by count per type plus structural inspection
- Rehearsal on real content with the editorial team
Cutover and after
- URL inventory and redirect mapping, activated with the cutover
- Crawl, indexation and impression tracking against the baseline
- An account of what was migrated, converted, or deliberately left
- What editors do differently, documented
- Where to change the model, and what depends on each part of it
Architecture and technology
What a headless model has to carry
- Content types that reflect meaning rather than page structure
- Fields typed to their content, not to their appearance
- References between content, as relationships rather than embedded copies
- Reusable components, so the same content can be composed differently per surface
- Assets as referenced objects, with every reference rewritten on migration
- Locales and variants, where content exists in more than one
- Editorial metadata: status, scheduling, authorship, revision
Where a headless migration loses content
- Presentation embedded in content, converted into meaning it does not have
- Relationships flattened, so the records arrive and the structure does not
- A content type with no destination, migrated into a generic field
- Media reference rewriting missed inside rich text
- One source of a duplicated content type migrated and the other left
- URLs changed without an inventory, so no redirect covers the old addresses
If this is not quite your problem
These overlap at the edges. Sending you to the right page is more useful than having you work it out.
The destination is WordPress, decoupled
Keeping WordPress for editors and replacing the rendering layer.
Headless WordPress developmentThe front end and the CMS are both changing
The two routes through a Next.js migration, and how to choose.
WordPress to Next.js migrationThe decoupled architecture more broadly
Choosing and building a decoupled stack.
Headless website developmentSearch visibility is the main risk
The general migration discipline, including redirects and indexation recovery.
Website migrationsFrequently asked
Which headless CMS do you recommend?
Which one fits follows from the requirements, and the pattern of content is a bigger factor than the feature comparison: whether content is mostly pages composed from components, mostly records that need querying, or a mixture. The requirements that decide it are how many surfaces consume the content, whether preview matters and in what form, how much the model is expected to change, and where the content is hosted. We will work through the choice with you and we will not claim a specialism in a product we have not delivered on — the modelling, mapping and migration work is the same whatever the destination is.
Why is this different from any other CMS migration?
Because there is no template layer. In a conventional CMS the model and the rendering sit close together, so a modelling decision can be absorbed or worked around in the theme. In a headless CMS every consumer reads the model directly, so the model is the interface — which means the design work is more consequential and the migration has to produce structure rather than pages. The rest of the discipline is the same: inventory, mapping, media, references, URLs, verification and measurement.
What happens to our layouts and page designs?
They are separated from the content. Conventional content frequently encodes presentation — styled blocks, positioning, page furniture — and a headless model carries meaning with each surface deciding how to render it. So part of this work is going through the existing content and deciding, item by item, what is meaning and what was appearance. It is the step that is most often underestimated, because it requires judgement rather than a mapping table, and getting it wrong produces a model that cannot be reused by a second surface — which is usually why headless was chosen.
Will our editors be able to work with it?
That depends on the destination and on how the model is designed, and it is a first-class requirement rather than a detail. A headless CMS shows content as fields rather than as a page, which some editorial teams find clearer and others find disorienting, and the preview experience is materially different. The model is reviewed with the people who publish, on real content, before the cutover — because changing it after several consumers depend on it is expensive, and the rehearsal is the cheap moment to find out that a field arrangement does not suit how they work.
Can you guarantee no content is lost?
What we guarantee is a complete method: an inventory of what exists, an explicit field mapping, a written list of content with no destination, reconciliation where the same content exists in more than one system, and verification by count per content type plus structural inspection of the relationships. A correct record count with flattened relationships is still a failed migration, so both are checked. Where content is deliberately not migrated, that is a recorded decision rather than an omission — and the list of those decisions is part of the handover.
Related capabilities and work
Bring us the problem you have not been able to fix
Describe what is happening rather than what you think the cause is. If we are not the right people for it, we will say so.