A practical website content migration plan separates deterministic extraction and writes from bounded content transformation, then validates every record before cutover. That architecture keeps an LLM away from permissions and final authority while giving ambiguous fields a reviewable path.
It turns a bulk import into a replayable pipeline with provenance, checkpoints, and explicit failure handling.
In this guide you will learn:
- How to separate deterministic work from ambiguous transformation
- What belongs in the migration pipeline
- Where a model should transform article fields
- How to validate every migrated article
- How to handle failures without corrupting the run
- How to dry-run and cut over safely
Key insights
- A migration run should produce an inspectable plan before it produces writes.
- The model may propose field content, but deterministic code owns identity, permissions, and publication state.
- Structural validity says JSON fits a schema; meaning has to be checked separately.
- A failed record belongs in a replayable queue with its inputs, outputs, and validation history.
- Cutover requires a freeze, backup, rollback path, and measurable exit criteria.
Why a website content migration plan needs clear ownership
Large imports fail when the person with write access is also defining mappings on the fly. Give the migration a small control plane, explicit owners, and a plan that can be inspected before execution.
If the CMS change sits inside a broader modernization strategy, keep this migration's contract separate from the wider program. A migration should have one source of truth for what changes, why it changes, and who can approve it.
Separate deterministic work from ambiguous transformation
Treat the run like a compiler. Resolve source-to-target mappings, field rules, and planned mutations before execution begins.
The compile phase reads source metadata and produces a manifest whose entries include the source identifier, target identifier, operation type, transformation version, and expected dependencies.
A wrong manifest can write the same duplicate slug twice.
The run phase executes that manifest. It does not invent new mappings because one article looks unusual.
If the manifest is wrong, stop the run, correct the mapping logic, and compile again.
A predictable migration separates planning from execution so you can inspect writes before they touch the destination CMS.
This design also makes review practical. Your team can inspect a sample of planned mutations, compare source and target fields, and approve the rules before broad execution.
Define what the model must never control
The model has no authority over destination credentials, record identity, permissions, deletion, publication state, redirects, or retry behavior. Deterministic code owns those decisions.
Keep the model inside a field-level transformation function with a strict input and output contract. The function can return a typed block, a proposed alt text, or a review status.
It cannot call the CMS, select an arbitrary destination, or approve its own output.
Use an allowlist for model-accessible fields. A request that asks for an unknown field should fail validation before the model runs.
A response that contains an unknown field should enter the dead-letter path instead of reaching the writer.
The migration orchestrator should also control prompt versions, token limits, timeouts, and model selection. Those settings belong in the run manifest, where you can reproduce the same transformation later.
What belongs in the migration pipeline?
A migration pipeline needs more than an importer. It needs durable stages that preserve the original content, produce canonical records, resolve dependencies, and expose each write for review.
The design should work for a small fixture and a large archive without changing its authority model.
Pantheon's October 2024 migration guide describes one Drupal 7 through Drupal 9 to Drupal 10 move.
It handled tens of thousands of entities and media items while preserving accessibility and SEO performance, a case-specific scale example.
Extraction, normalization, and canonical records
Start with an immutable raw landing zone. Store the source payload, retrieval timestamp, source endpoint, response headers, and checksum before parsing anything.
Normalization turns different source shapes into one canonical article record. The record might include:
sourceIdcontentTypetitleslugsummarybodyauthorpublishedAtupdatedAttaxonomymediaReferencessourceUrl
Keep raw and canonical data separate.
Raw data lets you rerun a parser after fixing a bug. Canonical data gives every later stage a stable contract.
Do not normalize away information you may need for reconciliation. Preserve source HTML, original URLs, embedded identifiers, and unknown markup alongside the cleaned representation.
IDs, URLs, redirects, and media dependencies
Create a stable identity from the source system rather than a title or slug, because titles change and source identifiers do not.
Maintain an explicit mapping table between source IDs, target IDs, canonical URLs, and migration runs. The writer should use that table for updates, so rerunning a record does not create a duplicate article.
Resolve dependencies before writing the article body. Media references, author references, taxonomy terms, and related articles should each have a target mapping or a visible failure state.
Prismic's May 2024 migration resources describe separate API scripts for retrieving documents, fetching them in batches, mapping fields, and issuing bulk create or update calls. Those scripts and the linked GitHub example ship separately from the CMS core.
Redirects deserve their own artifact. Generate them from the source-to-target URL map, test collisions, and preserve query-string behavior where your routing rules require it.
A redirect list hidden inside transformation code is difficult to review and harder to roll back.
Where should a model transform article fields?
Models belong after extraction and normalization, but before deterministic validation and writing. Their job is bounded: interpret ambiguous fields inside a fixed contract while the orchestrator runs the migration.
A good architecture makes the model's output look like any other untrusted external input. Parse it, validate it, compare it with source evidence, and route uncertainty to review.
Shortcodes and HTML blobs into typed blocks
Legacy articles often combine prose, inline markup, shortcodes, embeds, and layout assumptions inside one body field. Start with deterministic parsing for known patterns.
Convert recognized elements into typed blocks with explicit fields.
A video shortcode becomes a video block with a provider reference, caption, and fallback behavior. A heading becomes a heading block with a validated level.
A callout becomes a callout block with a body and optional title.
Use a model only for fragments that deterministic parsers cannot classify. Its response should identify the proposed block type, extracted content, supporting source fragment, and uncertainty reason.
Article field | Deterministic path | Model's bounded role | Write rule |
|---|---|---|---|
Title and slug | Preserve, normalize, and check collisions | Suggest a replacement only when explicitly requested | Keep the source field unless editorially approved |
HTML and shortcodes | Parse known tags and tokens | Classify unresolved fragments | Reject unknown block types |
Summary | Preserve existing text | Draft from the canonical body | Require editorial acceptance for generated text |
Taxonomy | Map known source terms | Suggest an unmapped term | Do not create new terms automatically |
Embedded media | Resolve source references | Explain an unrecognized embed | Stop the record when the asset is unresolved |
In OpenAI's August 6, 2024 structured outputs evaluation, gpt-4o-2024-08-06 reached 100% schema-following reliability on complex JSON schema tasks, versus less than 40% for gpt-4-0613. The result measures structural adherence, not semantic accuracy.
The February 16, 2026 LLMStructBench paper makes that distinction explicit. Its findings show that prompting can improve structural validity while increasing semantic errors, which is why application-level validation and abstention belong in the pipeline.
Missing alt text and other genuinely ambiguous fields
Missing alt text is a content decision when the source contains no usable description. The model can propose text from the image, caption, nearby copy, and article context.
It should return an empty result when that evidence is insufficient.
Treat generated alt text as a proposal. Preserve existing alt text unless an editorial rule says otherwise, and send weak or contradictory proposals to review.
The same boundary applies to summaries, tags, author matching, related articles, and legacy embed interpretation.
A model can surface a candidate. Deterministic code decides whether the candidate meets the field contract.
A July 2025 ACL paper reported a 1–3% F1 improvement for BLOCKIE over prior work on public visually rich document benchmarks. The result is domain-specific, and the paper notes that LLM methods struggle with layout clues in unseen formats.
How to validate every migrated article
Validation must answer two different questions: can the destination CMS store this record, and does the record still represent the source article correctly. Run validation before the write and after the write; the first pass protects the destination, while the second checks what the CMS actually stored, including generated IDs, references, rendered blocks, and URL behavior.
Schema and business-rule validation
Schema validation checks types, required fields, allowed block names, date formats, reference shapes, and media identifiers. It should reject malformed output before the writer receives it.
Business-rule validation checks meaning at the application boundary. Examples include:
- A published article must have a title, canonical URL, and publish date.
- A hero image must resolve to an approved media record.
- A heading block must use an allowed level.
- A redirect destination must not point to a deleted or unpublished record.
- A localized article must reference an approved source or translation relation.
Validate cross-record rules after individual records pass field checks. Duplicate slugs, circular related-content references, orphaned authors, and missing taxonomy mappings often appear only at the collection level.
A record can be valid JSON and still be wrong for your publishing model. Keep structural checks and business rules as separate results, so the failure explains what needs attention.
Reconciliation, provenance, and editorial acceptance
Reconciliation compares source and target inventories, identifiers, URL maps, media references, and publish states. Record expected counts from the source snapshot, then explain every difference instead of hiding it in a final total.
According to Sanity's April 15, 2026 migration tutorial, migrations are dry-run by default. Its example processed 179 documents, generated 179 mutations, and committed one transaction, while follow-up validation reported 444 valid documents and zero errors.
The same tutorial documents exporting and restoring the dataset before a write. Use that pattern with your destination's backup mechanism, then record the backup identifier in the run manifest.
Provenance should be queryable per field. Store the source fragment, parser version, model name, prompt version, model output, validation results, reviewer decision, and final target value.
Editorial acceptance should happen against rendered content as well as the stored JSON. Review a sample of standard articles, malformed legacy records, media-heavy pages, localized content, and records touched by model transformations.
How to handle failures without corrupting the run
Send a record to a dead-letter queue when parsing, transformation, dependency resolution, validation, or writing fails. The queue entry needs enough context for diagnosis without rerunning the entire import.
Dead-letter queues and replayable records
Store the source snapshot reference, canonical record, manifest version, failed stage, error class, input checksum, model request and response when relevant, retry count, and dependency status. Include the target ID if a write may have occurred.
Separate transient failures from permanent failures. A timeout may be replayed after backoff.
An unknown block type needs a parser or mapping change. A missing legal notice needs editorial action.
Replay should use the same source snapshot and transformation version unless you deliberately create a new run. Otherwise, the result can change while the failure is being investigated, leaving you unable to explain the difference.
Idempotency, backoff, and human review
Build an idempotency identity from the source system, source ID, target content type, and migration version. Before creating a record, check whether that identity already has a committed target operation.
Retries should be bounded and stage-specific. Back off for rate limits and transport errors.
Do not retry schema failures with the same payload, and do not retry a model response that contains unsupported fields without changing the contract or routing the record to review.
Human review should be a first-class state in the pipeline, with its own queue and its own transitions. The reviewer sees the source fragment, proposed transformation, validation findings, and the exact decision required.
A replay must be safe after a process crash.
Commit the operation result and status transition together where the destination supports transactions. Where it does not, reconcile the target by idempotency identity before retrying.
How to dry-run and cut over safely
A dry run is a production rehearsal with writes disabled. It should execute extraction, normalization, dependency resolution, model transformations, validation, manifest generation, and reporting.
The output should show what would change, which records need review, which redirects would be created, and which media references remain unresolved. A dry run that only counts rows tells you very little.
Fifty weird records before broad execution
Select fifty deliberately difficult records before broad execution. Include nested links, malformed HTML, old shortcodes, duplicate slugs, missing media, unusual Unicode, empty optional fields, long titles, and articles with several authors.
Run the full pipeline against that fixture. Inspect the raw payload, canonical record, planned mutation, rendered result, redirects, and provenance for each record.
Do not choose the sample from the first page of the source export. Pull records by failure history, content type, publication age, traffic importance, and template variation.
Fix the parser, mapping, or review rule when the fixture exposes a problem. Then rerun the same records.
A stable regression fixture is more useful than a dashboard that turns green after the sample changes.
Backups, checkpoints, rollback, and measurable exit criteria
AWS's cutover guidance, accessed August 11, 2026, recommends an ingestion freeze, final backup, data synchronization, routing changes, and testing. It also calls for predefined rollback criteria, checkpoints, rollback strategy, and tested backup-and-restore timing.
Write those conditions into the run plan before the freeze. A cutover meeting should confirm the evidence against those conditions.
Checkpoint | Evidence to capture | Decision |
|---|---|---|
Source freeze | Timestamp and blocked write path | Proceed with final extraction |
Destination backup | Backup identifier and restore test result | Proceed only when recovery is understood |
Final sync | Reconciliation report and unresolved-record list | Stop if unexplained differences remain |
Routing change | Smoke tests for canonical URLs, redirects, and media | Continue or restore previous routing |
Post-cutover review | Error queue, editorial sample, and monitoring findings | Keep the new path or roll back |
Use checkpoints that can be reversed independently where possible. A phased cutover limits the blast radius and gives your team a real comparison between old and new rendering paths.
Exit criteria should be measurable:
- Reconciliation differences are explained.
- Unresolved records have owners.
- Required redirects respond correctly.
- Media references resolve.
- Editorial review covers the agreed sample.
Where to start with the migration
Start by compiling the source inventory and migration manifest before asking a model to transform anything. That decision creates a controlled path from raw content to reviewed records, so a failed record costs you a replay rather than a corrupted archive.
Bring Blazity in for a headless CMS migration when we can read the source model, write the mapping, and own the cutover.
FAQ on website content migration plan
Should an LLM rewrite every article during a CMS move?
No, the model should transform only bounded fields that genuinely require interpretation. Preserve source content when deterministic parsing can handle it, and route uncertain transformations to editorial review.
What should a migration manifest contain?
The manifest should describe every planned operation before execution. Include source and target identities, field mappings, transformation versions, dependencies, expected redirects, and the permissions used by the writer.
How do you test redirects and media references?
Test them from the generated mapping artifacts before routing changes reach production. Check canonical URLs, redirect collisions, query strings, missing assets, unpublished targets, and representative rendered pages.
When is a migration ready for cutover?
Cut over only when every exit criterion has recorded evidence. That includes a recoverable backup, explained reconciliation results, tested routing, assigned unresolved records, and an agreed rollback path.
Sources
- Running a content migration – Handling schema changes confidently, Sanity (April 15, 2026)
- Introducing Structured Outputs in the API, OpenAI (August 6, 2024)
- LLMStructBench: Benchmarking Large Language Model Structured Data Extraction (February 16, 2026)
- Information Extraction from Visually Rich Documents using LLM-based Organization of Documents into Independent Textual Segments (July 2025)
- Ensure a Smooth Transition: The Comprehensive Guide to CMS Migration, Pantheon (October 4, 2024)
- Scripts for mapping content migration, Prismic (May 15, 2024)
- Cutover stage, AWS Prescriptive Guidance
%201.svg){kind=icon}