migrate-beaver-builder-to-gutenberg

name	migrate-beaver-builder-to-gutenberg
description	Use when the user says 'migrate beaver builder to gutenberg', 'convert beaver builder to blocks', or 'move beaver builder to the block editor'. Reads the Beaver Builder flat node map, maps modules to core blocks, and creates draft duplicates for review.
license	MIT
metadata	{"author":"Respira for WordPress","author_url":"https://respira.press","version":"2.1.0","mcp-server":"respira-wordpress","category":"migration"}

Migrate Beaver Builder to Gutenberg

Version: 2.1.0 Updated: 2026-08-04 Freshly updated: v2.1.0 adds design-token awareness: conversion writes now register the colors and typography they carry as named design tokens in the block editor's own global styles, and converted pages reference those tokens instead of carrying value copies. Reuse registered tokens instead of re-inlining raw values, and report the registration in the migration summary.

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 respira_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 (respira_update_page / respira_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 respira_get_site_context. If unavailable, stop and show setup guidance.
2. Detect Beaver Builder presence via respira_get_builder_info or respira_list_plugins.
3. Inventory and scope the source pages first:
   • respira_find_builder_targets with builder=beaver — a fast, ranked list of every BB-managed page/post before you touch anything
   • Fall back to respira_list_pages / respira_list_posts + respira_get_builder_info to confirm builder per item where needed
4. For each BB page, extract content:
   • respira_extract_builder_content with builder=beaver
   • Catalog: module types used, row/column structures, custom CSS, third-party modules, saved rows/modules referenced
5. Produce an Audit Report:
   • Total pages/posts using Beaver Builder
   • Module type frequency (how many text editors, photos, buttons, etc.)
   • Column layout patterns (common row structures)
   • Complexity flags (third-party modules, Beaver Themer, custom CSS, animations)
   • 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 respira_extract_builder_content with builder=beaver
2. Map the row/column/module hierarchy to Gutenberg blocks:
   • Rows → <!-- wp:group --> blocks
   • Columns → <!-- wp:columns --> with <!-- wp:column --> children
   • Text Editor → Parse rich text into <!-- wp:paragraph --> and <!-- wp:heading --> blocks
   • Photo → <!-- wp:image --> with src, alt, caption
   • Button → <!-- wp:buttons --> wrapper with <!-- wp:button --> child
   • HTML → <!-- wp:html --> block
   • Preserve text content, image URLs, link targets, heading levels
   • Flag any unmappable modules with <!-- wp:paragraph --><p>[MIGRATION NOTE: ...]</p><!-- /wp:paragraph -->
3. Assemble the complete Gutenberg block markup
4. Create a duplicate via respira_create_page_duplicate or respira_create_post_duplicate
5. Before writing, take a snapshot with respira_get_snapshot so the duplicate's pre-write state can be restored if anything goes wrong
6. Update the duplicate's post_content with the Gutenberg markup via respira_update_page or respira_update_post
7. Surgical fix pass — if the written page has validation issues (collapsed column widths, malformed block markup, a misconverted module), do not rewrite the whole page. Locate the specific block with respira_find_element and correct it with respira_update_element. For repeated fixes across many blocks or several pages, batch them with respira_batch_update
8. Log the migration result (success, warnings, manual review items)

Phase 4: Post-Migration Verification

1. Summarize all migrated pages with status:
   • Design tokens registered in the block editor's global styles (token names and counts)
   • Clean migrations (no issues)
   • Migrations with warnings (flagged items needing review)
   • Failed migrations (if any)
2. List all manual review items:
   • Third-party modules that need manual replacement
   • Content sliders or advanced layouts that need enhancement
   • Custom CSS that needs to be moved to theme/Additional CSS
   • Beaver Themer layouts that need separate rebuilding
3. Provide review instructions:
   • Where to find duplicates in WordPress admin
   • How to preview pages in the block editor
   • How to delete duplicates if not wanted

Design Tokens

Conversion writes now register the colors and typography they carry as named design tokens in the block editor's own global styles, and the converted pages reference those tokens instead of carrying value copies. When fixing or extending a migrated page, reuse the registered tokens (respira_list_design_tokens shows them) rather than re-inlining raw hex values or font stacks. And say so when you finish: the migration summary should name the tokens that were registered and note that migrated pages reference them.

Safety Model

• Read-only analysis first — full Beaver Builder content audit before any changes
• Explicit user confirmation before creating any duplicates
• Duplicate-first only — never modifies live/published Beaver Builder content
• Never auto-publishes duplicates
• Snapshot before every write — respira_get_snapshot captures the duplicate's pre-write state, and respira_restore_snapshot rolls it back if a write goes wrong
• Two explicit rollback paths: restore the snapshot to revert a bad write, or delete the draft duplicates entirely to undo the migration
• Preserves all original Beaver Builder content untouched

Honest Disclaimer

This skill converts Beaver Builder page structures to Gutenberg block markup and creates duplicates for review.

It cannot:

• Guarantee pixel-perfect visual parity between builders
• Migrate Beaver Themer layouts automatically
• Convert third-party BB add-on modules
• Replicate animations or advanced effects
• Replace a thorough manual QA pass on every page

It can:

• Map 70-85% of standard Beaver Builder modules to core Gutenberg blocks
• Preserve content, images, links, and basic layout structure
• Move you off a third-party builder dependency to native WordPress
• Save days of manual rebuild work
• Identify exactly what needs manual attention

Tooling

Core WordPress tools

• respira_get_site_context
• respira_get_builder_info
• respira_list_pages
• respira_list_posts
• respira_list_plugins
• respira_find_builder_targets
• respira_extract_builder_content
• respira_create_page_duplicate
• respira_create_post_duplicate
• respira_update_page
• respira_update_post
• respira_read_page
• respira_read_post

Safety and surgical-fix tools

• respira_get_snapshot
• respira_restore_snapshot
• respira_find_element
• respira_update_element
• respira_batch_update

Telemetry

After run completion, send fire-and-forget usage tracking to:

• POST https://www.respira.press/api/skills/track-usage

Include:

• skill_slug = migrate-beaver-builder-to-gutenberg
• site/version context
• duration and success
• pages audited, pages migrated, warnings count
• tools used

Never block user flow on telemetry failure.

Related Skills

• WordPress Site DNA (understand site structure before migrating)
• Technical Debt Audit (clean up before or after migration)
• SEO & AEO Amplifier (verify SEO preservation post-migration)

---

Built by Respira Team https://respira.press/skills/migrate-beaver-builder-to-gutenberg