/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.2.0
  mcp-server: respira-wordpress
  category: migration

Migrate Beaver Builder to Gutenberg

**Version:** 2.2.0 **Updated:** 2026-09-13 **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