migrate-beaver-builder-to-gutenberg

Migrate Beaver Builder to Gutenberg

Full-site migration from Beaver Builder to the WordPress block editor (Gutenberg). Audits every Beaver Builder page, maps modules to their Gutenberg block equivalents, builds a migration plan for approval, and executes page-by-page conversion into native block markup — all through duplicates so your live site stays untouched. Use this skill whenever someone mentions migrating from Beaver Builder to Gutenberg, switching from Beaver Builder to blocks, converting Beaver Builder pages to the block editor, or moving away from Beaver Builder to native WordPress.

What This Skill Does

Beaver Builder uses a module-based architecture with rows, columns, and modules stored in _fl_builder_data and _fl_builder_data_settings. Gutenberg uses a flat block structure in post_content with HTML comments as block delimiters. The architectural gap is moderate — Beaver Builder's row/column grid must be translated to Gutenberg's Group, Columns, and Column blocks, while individual modules map to core blocks.

This skill reads every Beaver Builder page, extracts the module structure, translates each row/column/module to its Gutenberg block equivalent, and writes the result to duplicate pages in native block markup — giving you a complete parallel version of your site to review before going live.

Handles:

• Row → Group block mapping
• Column layouts → Columns/Column block mapping
• Text Editor module → Paragraph/Heading blocks
• Photo module → Image block
• Button module → Buttons/Button block
• Video module → Video/Embed block
• HTML module → Custom HTML block
• Heading module → Heading block
• Icon/Icon Group modules → basic equivalents
• Separator module → Separator block
• Content slider → basic markup (flagged for enhancement)
• Call to Action module → Group + Heading + Paragraph + Button blocks

What This Skill Does NOT Do

• Migrate Beaver Builder's saved rows/modules library — these are separate entities
• Convert Beaver Themer layouts (headers, footers, archives, parts) — these must be rebuilt as block template parts or theme templates
• Replicate exact Beaver Builder animations/effects — Gutenberg has limited animation support
• Migrate advanced modules from third-party Beaver Builder add-ons (PowerPack, UABB, etc.) — flagged for manual handling
• Preserve exact column width percentages in all cases — Gutenberg columns have different width constraints
• Guarantee pixel-perfect visual parity — the block editor renders differently than Beaver Builder

Requirements

• Respira for WordPress plugin installed and connected
• MCP connection active (desktop or WebMCP)
• Beaver Builder active on the source site
• Read access to scan Beaver Builder content
• Write access to create duplicates with Gutenberg content

Trigger Phrase

• "migrate beaver builder to gutenberg"

Alternative Triggers

• "convert beaver builder to blocks"
• "switch from beaver builder to gutenberg"
• "move beaver builder to block editor"
• "replace beaver builder with gutenberg"
• "beaver builder to wordpress blocks"
• "migrate bb to gutenberg"

Builder Technical Context

Source: Beaver Builder

• Content stored in post_meta keys _fl_builder_data and _fl_builder_data_settings
• Module-based structure with rows → columns → modules hierarchy
• Read via wordpress_extract_builder_content with builder=beaver or builder=beaver-builder
• Module types: rich-text, photo, button, heading, html, video, icon, separator, callout, cta, numbers, content-slider, etc.

Target: Gutenberg (Block Editor)

• Content stored in post_content as HTML with block comment delimiters
• Format: <!-- wp:paragraph --><p>Text</p><!-- /wp:paragraph -->
• Write via standard WordPress content tools (wordpress_update_page / wordpress_update_post)
• Core blocks: paragraph, heading, image, buttons, columns, group, html, video, separator, embed, etc.

Execution Workflow

Phase 1: Pre-Migration Audit

1. Verify Respira + MCP connection via wordpress_get_site_context. If unavailable, stop and show setup guidance.
2. Detect Beaver Builder presence via wordpress_get_builder_info or wordpress_list_plugins.
3. Inventory all Beaver Builder content:
4. wordpress_list_pages and wordpress_list_posts — identify all content
5. wordpress_find_builder_targets with builder=beaver — find BB-managed pages
6. For each BB page, extract content:
7. wordpress_extract_builder_content with builder=beaver
8. Catalog: module types used, row/column structures, custom CSS, third-party modules, saved rows/modules referenced
9. Produce an Audit Report:
10. Total pages/posts using Beaver Builder
11. Module type frequency (how many text editors, photos, buttons, etc.)
12. Column layout patterns (common row structures)
13. Complexity flags (third-party modules, Beaver Themer, custom CSS, animations)
14. Estimated migration difficulty per page (simple / moderate / complex)

Phase 2: Migration Plan

Present a structured migration plan:

## Beaver Builder → Gutenberg Migration Plan

### Site Overview
- Total Beaver Builder pages: X
- Simple pages (direct mapping): X
- Moderate pages (some manual review needed): X
- Complex pages (significant manual work): X

### Module Mapping
| BB Module | Gutenberg Block | Notes |
|---|---|---|
| Text Editor | Paragraph / Heading | Content parsed into appropriate blocks |
| Photo | Image | Direct mapping |
| Button | Buttons > Button | Wrapped in Buttons container |
| Row (2 col) | Columns (2 col) | Width ratios preserved where possible |
| ... | ... | ... |

### Migration Order
1. [Page Title] — Simple — estimated 2 min
2. [Page Title] — Moderate — estimated 5 min
...

### Items Requiring Manual Attention
- [Page X] — PowerPack module (no core block equivalent)
- [Page Y] — Content slider (basic fallback only)
- Beaver Themer layouts — must be rebuilt as block templates

Then ask:

Here's the migration plan. Would you like me to:

1. Migrate all pages (creates duplicates for review)

2. Migrate only simple pages first

3. Migrate specific pages you choose

4. Just keep this as a reference — no changes

Wait for explicit confirmation before proceeding.

Phase 3: Page-by-Page Migration

For each approved page:

1. Extract Beaver Builder content via wordpress_extract_builder_content with builder=beaver
2. Map the row/column/module hierarchy to Gutenberg blocks:
3. Rows → <!-- wp:group --> blocks
4. Columns → <!-- wp:columns --> with <!-- wp:column --> children
5. Text Editor → Parse rich text into <!-- wp:paragraph --> and <!-- wp:heading --> blocks
6. Photo → <!-- wp:image --> with src, alt, caption
7. Button → <!-- wp:buttons --> wrapper with <!-- wp:button --> child
8. HTML → <!-- wp:html --> block
9. Preserve text content, image URLs, link targets, heading levels
10. Flag any unmappable modules with <!-- wp:paragraph --><p>[MIGRATION NOTE: ...]</p><!-- /wp:paragraph -->
11. Assemble the complete Gutenberg block markup
12. Create a duplicate via wordpress_create_page_duplicate or wordpress_create_post_duplicate
13. Update the duplicate's post_content with the Gutenberg markup via wordpress_update_page or wordpress_update_post
14. Log the migration result (success, warnings, manual review items)

Phase 4: Post-Migration Verification

1. Summarize all migrated pages with status:
2. Clean migrations (no issues)
3. Migrations with warnings (flagged items needing review)
4. Failed migrations (if any)
5. List all manual review items:
6. Third-party modules that need manual replacement
7. Content sliders or advanced layouts that need enhancement
8. Custom CSS that needs to be moved to theme/Additional CSS
9. Beaver Themer layouts that need separate rebuilding
10. Provide review instructions:
11. Where to find duplicates in WordPress admin
12. How to preview pages in the block editor