/migrate-brizy-to-gutenberg

name: migrate-brizy-to-gutenberg
description: "Use when the user says 'migrate brizy to gutenberg', 'convert brizy to blocks', or 'replace brizy with native wordpress'. Parses the Brizy JSON data, maps elements 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 Brizy 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 Brizy Builder to the WordPress block editor (Gutenberg). Audits every Brizy-built page, maps components 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 Brizy to Gutenberg, switching from Brizy to blocks, converting Brizy pages to the block editor, or moving away from Brizy to native WordPress.

What This Skill Does

Brizy uses a proprietary content format with its own component system, storing data in `brizy_post_uid` and related custom meta fields. Gutenberg uses a flat block structure in `post_content` with HTML comment delimiters. The migration requires extracting Brizy's custom format, identifying each component type, and translating it to equivalent core Gutenberg blocks.

This skill reads every Brizy page, extracts the builder content, translates each component 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:**

• Section → Group block mapping
• Row/Column → Columns/Column block mapping
• Text components → Paragraph/Heading blocks
• Image components → Image block
• Button components → Buttons/Button block
• Video components → Video/Embed block
• Icon components → basic equivalents
• Spacer/Divider → Spacer/Separator blocks
• Map component → basic embed fallback
• Form elements → flagged for manual handling (Contact Form 7 or similar)
• Custom HTML/embed content

What This Skill Does NOT Do

• Migrate Brizy's global styling system — must be recreated in theme settings or Global Styles
• Convert Brizy popup designs — Gutenberg has no native popup system
• Replicate Brizy's built-in form submissions — a separate form plugin is needed
• Migrate Brizy Cloud templates or synced content
• Convert Brizy Pro dynamic content features — flagged for manual handling
• Preserve Brizy's hover effects and animations — Gutenberg has limited animation support
• Guarantee pixel-perfect visual parity — different rendering approaches

Requirements

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

Trigger Phrase

• "migrate brizy to gutenberg"

Alternative Triggers

• "convert brizy to blocks"
• "switch from brizy to gutenberg"
• "move brizy to block editor"
• "replace brizy with gutenberg"
• "brizy to wordpress blocks"
• "migrate brizy to native wordpress"

Builder Technical Context

**Source: Brizy**

• Content stored in post_meta key `brizy_post_uid` and Brizy's custom format
• Proprietary component structure with sections, rows, columns, and elements
• Read via `respira_extract_builder_content` with `builder=brizy`
• Components: sections, rows, columns, text, image, button, video, icon, spacer, map, form, embed, 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`, `spacer`, `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 Brizy presence via `respira_get_builder_info` or `respira_list_plugins`. 3. Inventory all Brizy-built content:

• `respira_list_pages` and `respira_list_posts` — identify all content
• `respira_find_builder_targets` with `builder=brizy` — find Brizy-managed pages

4. For each Brizy page, extract content:

• `respira_extract_builder_content` with `builder=brizy`
• Catalog: component types used, nesting depth, popups, forms, dynamic content usage

5. Produce an **Audit Report**:

• Total pages/posts using Brizy
• Component type frequency (how many sections, text blocks, images, etc.)
• Complexity flags (popups, forms, dynamic content, Brizy Pro features)
• Estimated migration difficulty per page (simple / moderate / complex)

Phase 2: Migration Plan

Present a structured migration plan:

## Brizy → Gutenberg Migration Plan

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

### Component Mapping
| Brizy Component | Gutenberg Block | Notes |
|---|---|---|
| Section | Group | Container mapping |
| Row / Columns | Columns / Column | Layout structure |
| Text | Paragraph / Heading | Content parsed into blocks |
| Image | Image | Direct mapping |
| Button | Buttons > Button | Wrapped in container |
| ... | ... | ... |

### Migration