How to migrate a WordPress site into ACF blocks (2026 guide)

The hardest part of any WordPress rebuild is not the design or the theme — it is moving years of content into your new block structure. If your new build is based on Advanced Custom Fields, every hero, card grid, stats row and FAQ has to land in the right block with the right fields. Done by hand, a 60-page site is a week of copy-and-paste. This guide walks through a faster, repeatable workflow that agencies use on every builder exit: export, spec, crawl, review, import, redirect, monitor.

Whether the old site runs Elementor, WPBakery, Divi, flexible content, or plain Classic Editor HTML, the destination is the same — native ACF blocks in Gutenberg. The source markup differs; the workflow does not.

What you need before you start

• arrow_rightYour new build running WordPress 6.4+ with ACF Pro and your ACF blocks registered.
• arrow_rightAn ACF JSON export of the field groups your pages use.
• arrow_rightA publicly reachable copy of the old site to migrate from.
• arrow_rightThe free ACF Migrate importer plugin installed on the new site.
• arrow_rightA redirect plan if URL structure is changing.
• arrow_rightYoast or Rank Math on the destination if you are migrating SEO metadata.

Step 1 — Register blocks and export field groups

Your field-group export is the blueprint. It tells the migration exactly which blocks exist, what their field keys are, and how repeaters are structured. Register every block first — see how to register ACF blocks. Then in WordPress admin, go to ACF → Field Groups, tick the groups your templates use, and choose Export → Export As JSON. Or use local JSON in acf-json/ — see ACF JSON export explained.

Step 2 — Build a mapping spec

A mapping spec is the rulebook that decides which old-site section becomes which ACF block. Good specs distinguish near-identical blocks (testimonial vs plain quote) and know how to fill repeater sub-fields. With AIRA, you upload the ACF export and the spec is generated — every placeable block, field key and repeater is learned automatically, and AI writes the trigger rules. Save the spec for future projects on the same block library.

Step 3 — Crawl the old site

Point the crawler at the old URL. It discovers the sitemap, reads each page with the full DOM intact, and classifies every section into one of your ACF blocks — attaching a confidence score to each. Use include/exclude path filters and a max-pages cap so you only migrate what matters and skip /tag/ and /author/ archives.

Step 4 — Review flags and commit

Before spending credits, review low-confidence classifications and failed crawls. Re-run with adjusted path filters if needed. Crawling and preview are free in AIRA — you only spend credits when you commit and download the import bundle. See how to use AIRA for the full app walkthrough.

Step 5 — Import as drafts

1. 1Open the bundle in the ACF Migrate importer (Tools → ACF Migrate).
2. 2Expand each page to see its blocks in order, with confidence scores and review flags.
3. 3Reassign any mis-classified block, reorder, or drop junk sections.
4. 4Choose Draft and import — nothing goes live until you review and publish.
5. 5Verify images sideloaded and internal links rewritten.

Step 6 — Review pass in Gutenberg

1. 1Sort by lowest confidence score — fix these first.
2. 2Check page title and slug match your URL map.
3. 3Count repeater rows: team (6 people?), FAQs (12 items?), logos (8 brands?).
4. 4Open in Gutenberg — blocks visible in editor, not empty placeholders.
5. 5Preview front-end — compare side-by-side with old site on key pages.
6. 6Spot-check image attachment IDs in ACF image fields vs hotlinked URLs.

Step 7 — SEO, redirects and launch

If your URL structure changes, you will lose rankings unless you redirect old paths to new ones. Generate a redirect map (old → new) and import into Redirection, Rank Math, or .htaccess. Migrate Yoast or Rank Math metadata with the bundle. Run the migration QA checklist and SEO preservation guide before cutover. Monitor with post-launch monitoring for four weeks.

Builder-specific notes

The workflow is identical across builders; only the source markup differs. Elementor stores layout in post meta — crawl the rendered page. WPBakery uses shortcodes — same rule. Divi, Beaver Builder, Oxygen — all crawl front-end. See dedicated guides for Elementor, WPBakery, Divi, and flexible content sources.

Mapping quality determines migration quality

The classifier can only place sections as well as your blocks describe themselves. Name blocks for what they are — hero, testimonial, card-grid — not grey-box-left. Design fields to match content types. Define fallback rules for unmatched sections. See how to map website sections to ACF blocks.

Troubleshooting common issues

Cost and scoping

AIRA pricing is per-page — one credit per page committed. Crawling and classification are free. For agency quoting, price migration per page and map credits to COGS. See how to scope and price a rebuild and AIRA vs manual. Agencies reuse saved specs across clients on the same block library.

Post-import cleanup

• arrow_rightRun shortcode cleanup if any debris remains.
• arrow_rightDeactivate old page builder only after sign-off on staging.
• arrow_rightTrain editors on Gutenberg blocks before cutover.
• arrow_rightKeep staging clone for two weeks as rollback insurance.

Staging workflow before production import

Never import directly to production first. Run the full workflow on staging: register blocks, upload JSON, crawl, commit, import drafts, QA, client review, then promote to production via deploy or re-import. See WordPress staging migration workflow for environment parity checks.

Path filters and crawl scope

• arrow_rightExclude /tag/, /author/, /page/N/ archive paths unless needed.
• arrow_rightInclude only /about/, /services/, /contact/ paths on brochure sites.
• arrow_rightMigrate blog posts separately if they map to core blocks, not ACF.
• arrow_rightSet max-pages cap during pilot crawl to validate mapping before full commit.
• arrow_rightPassword-protected staging: allowlist crawler IP or use temporary public access.

Multilingual migrations

WPML and Polylang sites have duplicate pages per locale. Crawl each language path or use path filters per locale. Field keys are shared across languages — content values differ per post. Redirect maps need every locale variant. Budget page count as pages × languages for credits and quoting.

Timeline expectations

Roles and responsibilities

Common migration failure modes

• arrow_rightImporting before blocks registered on staging — empty editor fields.
• arrow_rightChanged field keys between crawl and import — silent data loss.
• arrow_rightPublished drafts without front-end QA — broken repeaters live.
• arrow_rightNo redirect map when URLs changed — rankings cliff in week one.
• arrow_rightDeactivated source builder before re-crawl needed — cannot regenerate bundle.
• arrow_rightSkipped SEO plugin install on destination — metadata import fails.

End-to-end checklist

1. 1Register blocks and export JSON.
2. 2Upload export, generate spec, run pilot crawl on 5 pages.
3. 3Review classifications, adjust spec if needed.
4. 4Full crawl, commit credits, download bundle.
5. 5Import drafts on staging via ACF Migrate plugin.
6. 6Gutenberg and front-end QA on top 20 pages.
7. 7Load redirects, verify SEO metadata.
8. 8Client sign-off, publish incrementally, monitor 4 weeks.

What success looks like

A successful migration: every marketing page exists as a Gutenberg draft with structured ACF blocks, images in the Media Library, internal links pointing at new URLs, SEO metadata populated, redirects loaded, and editors trained before publish. The old builder is deactivated without content loss. Search Console shows stable indexation within four weeks. That is the bar — not 'we copied the HTML somewhere'.

Keep the spec for next time

Save your AIRA mapping spec after the project. The next client on the same block library skips spec generation entirely — one of the highest-ROI habits an agency can build.

Migration is not a theme switch. It is a structured content move from rendered sections to field keys — and it deserves its own phase in the project plan.

Deep dive on import: import an ACF Migrate bundle. Plugin details: ACF Migrate integration. Pricing: AIRA pricing.