ACF block migration
ACF block migration is the process of moving page content from a legacy builder or theme into native Advanced Custom Fields blocks registered in your theme, preserving field keys and block structure.
Unlike a database clone, block migration restructures content: each hero, card grid, testimonial row, or FAQ accordion on the old site must land in the correct ACF block with the correct repeater rows and sub-fields. Agencies do this during redesigns when they exit Elementor, Divi, WPBakery, or a bespoke theme and rebuild on a native block library.
The workflow typically runs in four phases: register your target block library and export ACF JSON; crawl or export the old site's rendered pages; classify each section into a block and fill fields; import as drafts, sideload media, rewrite internal links, and ship a redirect map. Tools like AIRA automate classification and import; your team still owns templates, CPTs, forms, and launch QA.
Advanced Custom Fields (ACF)
Advanced Custom Fields (ACF) is a WordPress plugin that lets developers define structured field groups — text, images, repeaters, relationships — attached to posts, pages, options screens, or custom post types.
On agency rebuilds, ACF is the content layer behind native Gutenberg blocks: each block template reads ACF fields instead of storing layout in a page builder's proprietary JSON. Field keys (not just labels) must stay stable across environments so JSON sync and migration imports do not break.
ACF Pro adds repeater, flexible content, gallery, and clone fields — the building blocks of composite sections like card grids and team rows. When migrating, map old visual sections to ACF blocks that match how editors will maintain the site after launch, not how the legacy builder stored data.
ACF blocks
ACF blocks are custom Gutenberg blocks registered with acf_register_block_type(), where the block template and fields are defined in ACF field groups rather than in page-builder widgets.
Each ACF block has a slug (e.g. hero, card-grid), a PHP or Twig render template, and a linked field group. WordPress stores block content as HTML comments with JSON attributes — the same serialize_block() format core blocks use — which makes exports predictable and migration-friendly.
Agency block libraries usually include 10–20 composite blocks (hero, features, testimonials, FAQ, CTA) plus atomic fallbacks (rich text, image, quote) for edge-case sections. Migration succeeds when your library covers the section types on the old site before you start classifying pages.
Gutenberg blocks
Gutenberg blocks are the native WordPress content units introduced in the block editor — each paragraph, image, column, or custom block is stored as structured block markup in post_content.
ACF blocks are a subset of Gutenberg blocks: they appear in the inserter, respect block supports (alignment, spacing), and serialize into post_content. Page builders like Elementor often bypass this model and store layout in postmeta, which is why exiting a builder requires a migration step rather than a theme switch.
After an ACF migration, editors work entirely in Gutenberg with your registered blocks — no builder plugin required on the front end. That reduces CSS bloat, improves Core Web Vitals, and makes long-term maintenance predictable for agency retainers.
Page builder exit
A page builder exit is the deliberate process of deactivating Elementor, Divi, WPBakery, or similar tools after content has been rebuilt in native theme blocks, without losing layout, SEO, or editor usability.
Builders store layout in proprietary formats — Elementor's _elementor_data JSON, Divi shortcodes, WPBakery vc_row tags. Deactivating the plugin before migration leaves raw shortcodes on the front end. The exit sequence is: build the new block library, migrate content into it, validate redirects and SEO, then remove the builder plugin on go-live.
Exits fail when teams underestimate CPT archives, global headers, forms, and blog posts still containing builder markup. Budget the exit as a project phase, not a checkbox after design sign-off.
Content mapping
Content mapping is the ruleset that defines which old-site section types become which ACF blocks and which field keys receive each piece of text, image, or repeater row.
Manual mapping means a developer eyeballs each page and copies values field by field. Automated mapping uses a spec derived from your ACF JSON export plus AI or rule-based classification of rendered HTML sections. The spec should label blocks as composite (hero, card-grid) or atomic (paragraph, image) and define fallbacks when no block matches.
Good mapping preserves editorial intent: a three-column feature row should become a features repeater, not a single WYSIWYG blob. Review confidence scores before import — low-confidence blocks are where migrations silently lose structure.
Custom post type (CPT)
A custom post type (CPT) is a WordPress content bucket beyond posts and pages — common examples include portfolio items, case studies, team members, testimonials, and resources, each with its own templates and ACF fields.
CPT migration is separate from marketing page migration. Records live in wp_posts with a custom post_type value; URLs may use archive and single templates your theme registers. Importing pages as drafts does not move CPT entries unless you explicitly export and map them.
Plan CPT work early: register the post type and field groups on the new theme, migrate records (WXR, WP-CLI, or crawl-and-map for simple singles), rebuild archive templates, and add redirects if slugs change. Portfolio-heavy agency sites often have more CPT risk than homepage risk.
ACF JSON export
ACF JSON export is the field-group definition file generated from ACF → Tools → Export, used to sync field keys across environments and as the target schema for migration mapping.
The export lists every block-linked field group, repeater structure, and field key your theme expects. Migration tools read this file to know valid block slugs and where to place crawled content. Never rename field keys between export and import without a deliberate migration script — editors and imports both depend on key stability.
Store JSON in your theme's acf-json folder for version control. When the block library changes mid-project, re-export and re-run classification on affected pages before committing import credits.
Flexible content vs ACF blocks
Flexible content is an ACF Pro field that stores a stack of named layouts in one field group; ACF blocks are separate Gutenberg blocks, each with its own field group and inserter entry.
Flexible content suits pages built as a vertical stack of sections inside one editor container. ACF blocks suit design systems where each section is a distinct block in Gutenberg with clearer preview and block-level locking. Many agencies standardise on blocks for client rebuilds because editors see WYSIWYG previews per section.
Migrating into flexible content means choosing layout names per section; migrating into blocks means choosing block slugs. Pick one model per site — mixing both on the same page without a documented pattern confuses editors and mapping rules.
Media sideloading
Media sideloading is importing images and files from a source URL into the WordPress Media Library on the new site, creating new attachment IDs and updating references in content and ACF image fields.
Broken images after migration almost always mean attachment IDs in post meta still point at the old database, or content still hotlinks to the old domain. Sideload during import, then run a search-replace for hardcoded URLs in post_content and ACF fields.
Map alt text from old img tags into attachment meta and ACF image sub-fields. Featured images, Open Graph images, and background images in ACF each need explicit QA — not just the hero photo on the homepage.
Redirect map
A redirect map is a list of 301 redirects from old URLs to new URLs, shipped at launch so search rankings and bookmarks survive a redesign or permalink structure change.
Build the map during discovery when you inventory old URLs and decide new slugs — not the night before go-live. Include pages, posts, CPT singles, category archives, and legacy campaign landings. Import into Redirection, Rank Math, Yoast Premium, or server config.
Pair redirects with Search Console URL inspection on top landing pages after launch. A rebuild without redirects is one of the fastest ways to lose organic traffic agencies were hired to protect.
Section classification
Section classification is the step where each visual segment of a rendered page — hero, logo strip, testimonial carousel — is labelled with a target ACF block type and field mapping before import.
Rule-based scrapers classify by CSS selectors; AI classification reads surrounding copy and layout context the way a developer would ('this three-column row with icons is a features block'). Hybrid workflows use AI for judgement and deterministic code for import into serialize_block() output.
Confidence scores per classified block flag sections for human review. Always review low-confidence rows before publishing — they are where wrong block types and empty repeaters hide.
Confidence score
A confidence score is a per-block rating — usually 0–100 — indicating how certain the classifier is that a crawled section matches the assigned ACF block and field mapping.
Treat scores as a review queue, not a pass/fail gate. A 92% hero classification may still have the wrong CTA link; a 61% card grid may be correct but unusual layout. Agency workflow: sort by ascending score, fix block assignments and repeater counts, then import as drafts.
AIRA surfaces scores in the crawl review UI before you spend credits on bundle download. Free crawl and classify means you can validate mapping quality on one representative page before committing a full site.
WordPress staging migration
WordPress staging migration is running the full content move on a staging environment first — import drafts, QA blocks, test redirects and forms — before pushing to production.
Never first-import directly to production on a client rebuild. Staging catches broken repeaters, missing CPT templates, form plugin misconfigurations, and SEO meta gaps. Use path or host differences to block indexing on staging (noindex or HTTP auth).
The staging → production step for ACF block content is usually a controlled re-import or database merge of reviewed posts — not a repeat crawl. Document which environment owns the canonical redirect map.
Yoast SEO migration
Yoast SEO migration is preserving _yoast_wpseo_title, meta description, canonical, and schema-related post meta when posts move to a new theme or URL structure.
Yoast meta travels with WXR or page bundles if you include postmeta. After block migration, validate titles and descriptions still match visible content — auto-generated snippets from old builder pages may reference removed sections.
Reconnect Google Search Console after launch, submit the new sitemap, and monitor Coverage for soft 404s on redirected URLs. Rank Math and SEOPress follow the same principle with different meta key prefixes.
Elementor migration
Elementor migration is moving content out of Elementor's widget-based layout stored in _elementor_data into native ACF blocks or Gutenberg blocks without leaving Elementor shortcodes in post_content.
Crawl the rendered front-end HTML rather than parsing Elementor JSON directly — rendered output reflects what visitors and search engines saw. Global headers, theme builder templates, and popup content are separate workstreams from page body migration.
Expect repeaters for icon boxes, sliders, and testimonial carousels. Pair page migration with CPT, menu, and form guides if the site uses Elementor Pro loops or dynamic tags.
ACF Migrate plugin
The ACF Migrate plugin is the WordPress importer that reads an AIRA bundle.json file and creates draft posts with native ACF block markup, sideloaded media, and migrated SEO meta.
Install it on the target site after your block library is registered and ACF JSON is synced. The bundle is generated when you commit a crawl in the AIRA app — one credit per page in the bundle. Review and edit drafts in Gutenberg before publish.
The plugin expects field keys in the bundle to match the active theme's ACF registration. Version-control your block library and re-import if field groups change after a bundle was generated.
serialize_block()
serialize_block() is WordPress's PHP function that converts a block structure array into the HTML-comment JSON format stored in post_content — the canonical storage format for Gutenberg and ACF blocks.
Reliable ACF migration outputs serialize_block() markup using your registered block names and ACF field values, not raw HTML pasted into the classic editor. That keeps blocks editable in the inserter after import and compatible with block validation.
When evaluating migration tools, ask whether output is real block markup or HTML blobs inside a custom HTML block. Only the former behaves like a native rebuild for long-term client editing.