Sanity to WordPress Migration: Plan Portable Text, References and the Editor Experience
A buyer guide to mapping Sanity documents and custom rich-text blocks into a maintainable WordPress publishing model.
In this article
Illustrative workspace. Screens show concepts, not a delivered client system.
A Sanity website is shaped by its documents, schema definitions and frontend rendering. Copying the visible text into WordPress may lose the references, custom blocks and editing rules that make the content reusable. A Sanity to WordPress migration needs an agreed destination model before the wider import begins.
My Sanity to WordPress migration service assesses the dataset, source configuration and website requirements before scoping the WordPress build. This guide helps your team distinguish content transfer from the work needed to preserve its meaning and editing experience.
Decide what will happen to the dataset and its other consumers
List every application that uses the content in scope. WordPress might replace the public marketing website while other consumers remain connected to Sanity. Alternatively, the project might move the publishing source as well. These are different boundaries with different release responsibilities.
Record the dataset, document types, website routes and who owns the schema and frontend code. Include the team that can explain custom Studio behaviour. Documents tell you the values; the source configuration and rendering explain how those values are edited and presented.
Check the export and the content states it includes
Sanity documents dataset exports as a way to retrieve source documents and assets. Confirm the selected dataset, document types, publication states and media availability. An export needs transformation into the WordPress destination; it does not recreate the frontend or Studio controls.
Build a reconciliation list for the records your team has approved to move. Keep source identifiers so references can be resolved after the first records are created. Review missing or intentionally excluded documents rather than silently dropping their relationships.
Map Portable Text by behaviour, not just appearance
Sanity’s Portable Text documentation describes structured rich text that is rendered into the required output. A WordPress migration needs rules for headings, links, annotations and any custom objects within that text. Ordinary paragraphs may be straightforward; a custom product card or embedded resource needs a separate decision.
| Portable Text pattern | Question for the WordPress implementation |
|---|---|
| Text and heading blocks | How will formatting and the heading hierarchy be preserved? |
| Annotations and internal references | What destination should each link or reference resolve to? |
| Custom embedded object | What should render, and which controls should the editor receive? |
| Image or file object | Which media record and presentation details should be retained? |
Use a sample with the blocks your editors actually use. A plain-text extraction can be useful for review, but it is not evidence that the complete article experience has migrated.
Preserve reusable documents and meaningful media details
Shared authors, categories, promotions or product references need destination ownership. Decide whether WordPress will represent them as structured records, taxonomies or shared Elementor sections. Avoid duplicating shared values across page bodies without an update plan.
Review the images and files referenced by the approved content. Where the source contains meaningful crop or focal-point information, decide how the new layouts will use it. Check descriptions, links to downloads and availability of the actual binaries. The replacement should show the right content, not just a similarly sized image.
Validate publishing and preview with an editor
A useful pilot includes a reference-heavy document, a custom rich-text block and an image. Have the content owner review the source and destination side by side. Ask an editor to change a reference, edit a block and preview the result.
- Check the intended published and draft states.
- Verify reusable content relationships and custom object output.
- Compare links, image presentation and important metadata.
- Document the equivalent editor controls and any deliberate simplifications.
If the new website uses Elementor, agree which content belongs in native page widgets and which benefits from structured fields. The aim is an editing workflow your team can operate consistently, rather than a visual copy that is difficult to maintain.
Plan routes and a final content update
Your current frontend may compute a URL from document fields or reference relationships. Inventory public addresses separately from document IDs and map them to approved WordPress destinations. Include article links, category pages and downloads in the release review.
Agree the content freeze or final update process with the source owner. Also decide which Sanity connections stay active for other applications. Hosting changes, redirects, recovery responsibilities and post-release checks belong in the wider migration plan.
Send a brief that explains your custom content
Include the public website, dataset scope, document-type summary and examples of custom Portable Text blocks. Describe references, images, languages, previews and other consumers. Add the desired editing workflow and target release window.
I can then assess the destination mapping, templates, content movement and any custom WordPress features needed for the agreed behaviour. Request a Sanity migration scope discussion before committing to a complete transfer. Access and implementation assumptions should be resolved in the proposal, not discovered at launch.
Written by
Jagjeet Singh
Full stack development, WordPress engineering and practical web products. I work with businesses, teams and agencies in India and worldwide.
Explore my work
