/wp-migrate

description: Migrate existing WordPress content (Classic Editor, ACF, widgets, CPTs, shortcodes, page builders) into a block theme.

/wp-migrate

**Purpose:** Generate the code, queries, and patterns needed to migrate existing WordPress content — classic editor posts, widget areas, ACF fields, shortcodes, or Custom Post Types — into the new block theme structure.

When to Use

Trigger this command when:

• The user has an existing WordPress site (not a static HTML project) they are upgrading to a block theme
• The user wants to convert Classic Editor content to block editor content
• The user has custom fields (ACF, CMB2, Meta Box) they want to surface via Block Bindings API
• The user has widget areas they want to replace with template parts
• The user has shortcodes they want to replace with blocks or patterns
• The user has a Custom Post Type they want to surface via Query Loop or a custom dynamic block

This command is NOT for converting static HTML → WordPress (use `/convert-to-wp-theme` for that).

Page Builder Detection

If the user mentions or you detect a page builder in scope, load `references/page-builder-migration.md` **before** Step 2. That reference contains per-builder playbooks with element→block mapping tables, WP-CLI extraction commands, and worked examples. Use the builder-specific workflow from that reference instead of the generic approach below for content extraction.

| Builder detected | Action | |-----------------|--------| | Elementor / Elementor Pro | Load page-builder-migration.md §1 | | Divi / Divi Builder | Load page-builder-migration.md §2 | | WPBakery / Visual Composer | Load page-builder-migration.md §3 | | Beaver Builder / BB Themer | Load page-builder-migration.md §4 | | Classic Gutenberg (no builder) | Load page-builder-migration.md §5 | | None / unknown | Continue with generic workflow below |

Workflow

Step 1: Identify Migration Scope

Ask (or infer from context):

| Question | Why it matters | |----------|---------------| | WordPress version currently running | Determines available migration tools | | Active page builder (Elementor, Divi, Beaver Builder, WPBakery, none) | Different conversion strategies per builder — see page-builder-migration.md | | Using Classic Editor or already using Gutenberg? | Classic content needs block conversion | | Custom Post Types (CPTs) — list their slugs | Need Query Loop templates or custom blocks | | Custom fields plugin (ACF, CMB2, Meta Box, Pods, none) | Determines Block Bindings approach | | Widget areas — list names and their content | Become template parts in block theme | | Shortcodes in use — list them | Need block or pattern equivalents | | How many posts/pages need migration (estimate) | Batch vs programmatic migration | | WooCommerce products? | WooCommerce-specific template migration |

Step 2: Produce a Migration Map

Before writing any code, output a table mapping old content to its new block equivalent:

MIGRATION MAP
==============
| Old Element                        | New Block Equivalent                    | Migration Method      |
|------------------------------------|----------------------------------------|----------------------|
| Classic Editor post                | Block editor post (auto-convert)        | Content Transform API |
| [hero] shortcode                   | my-theme/hero pattern                   | Shortcode replacement |
| sidebar widget area                | parts/sidebar.html template part       | Template part         |
| footer widget area                 | parts/footer.html (already exists)     | Template part         |
| ACF field: `hero_headline`         | Block Binding → post meta              | Bindings API          |
| CPT: `project`                     | Query Loop + custom template part      | Template hierarchy    |
| Elementor template: Landing Page   | FSE page template                      | Manual rebuild        |

Show this map and get user confirmation before generating code.

Step 3: Execute Migration by Category

Handle each category in order:

---

Category A: Classic Editor Content → Block Editor

WordPress's built-in parser handles most of this automatically. Provide:

**1. PHP script to audit content (run via WP-CLI or a one-off plugin):**

<?php
// Identify posts still using classic editor content (no block markup).
// Run via: wp eval-file audit-classic-content.php

$posts = get_posts( array(
    'post_type'      => 'any',
    'posts_per_page' => -1,
    'post_status'    => array( 'publish', 'draft', 'private' ),
) );

$classic_posts = array();
foreach ( $posts as $post ) {
    if ( ! has_blocks( $post->post_content ) ) {
        $classic_posts[] = array(
            'ID'         => $post->ID,
            'post_type'  => $post->post_type,
            'post_title' => $post->post_title,
            'edit_url'   => get_edit_post_link( $post->ID ),
        );
    }
}

echo 'Classic Editor posts: ' . count( $classic_posts ) . PHP_EOL;
foreach ( $classic_posts as $p ) {
    echo sprintf( '[%d] %s (%s) — %s', $p['ID'], $p['post_title'], $p['post_type'], $p['edit_url'] ) . PHP_EOL;
}

**2. Bulk conversion note:**

WordPress automatically wraps Classic Editor paragraphs in `<!-- wp:paragraph -->` blocks when displayed in the block editor. For most text content this is sufficient. For complex layouts (tables, floated images, shortcodes), manual editing is needed.

---

Category B: Shortcodes → Blocks / Patterns

For each shortcode, provide:

1. The block or pattern equivalent 2. A PHP filter to render the block equivalent instead of the shortcode (for programmatic posts) 3. A WP-CLI command to find all posts using the shortcode

**Finding all shortcode usages:**

wp post list --post_type=post,page --format=ids | xargs -I{} wp post get {} --field=post_content | grep -c '\[{{shortcode_tag}}'

**Replacing shortcodes in existing content (WP-CLI batch):**

wp search-replace '[{{shortcode_t