/migrate-divi-to-gutenberg

name: migrate-divi-to-gutenberg
description: "Use when the user says 'migrate divi to gutenberg', 'convert divi to blocks', 'get off divi', or 'decommission divi'. Parses Divi shortcodes, 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 Divi 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.

Converts Divi-built WordPress pages to native Gutenberg blocks. Parses Divi's shortcode-based content from post_content, maps each module to its closest core block equivalent, generates a migration plan for approval, and writes clean block markup to the target pages. Use this skill whenever someone wants to move from Divi to Gutenberg, eliminate the Divi dependency, switch to native blocks, or simplify their WordPress stack by removing Elegant Themes' builder.

What This Skill Does

Divi stores everything as nested shortcodes directly in `post_content` — a fundamentally different approach from JSON-based builders. The content is a hierarchy of `[et_pb_section]`, `[et_pb_row]`, `[et_pb_column]`, and `[et_pb_module]` shortcodes with settings as attributes. Converting this to Gutenberg blocks means parsing that shortcode tree, extracting content and settings, and generating the equivalent `<!-- wp:block -->` markup.

This is one of the more complex migrations because Divi shortcodes often contain escaped HTML, base64-encoded content, and deeply nested attribute strings that need careful parsing.

**Handles:**

• et_pb_section → Group block with layout settings
• et_pb_row/et_pb_column → Columns and Column blocks
• et_pb_text → Paragraph blocks (with inline HTML preserved)
• et_pb_blurb → Group block with Image + Heading + Paragraph
• et_pb_image → Image block
• et_pb_button → Buttons block
• et_pb_video → Video or Embed block
• et_pb_divider → Separator block
• et_pb_slider/et_pb_slide → Gallery or Group blocks (simplified)
• et_pb_accordion/et_pb_accordion_item → Details blocks (WP 6.3+)
• et_pb_tabs/et_pb_tab → Group with heading blocks
• et_pb_toggle → Details block (WP 6.3+)
• et_pb_code → Custom HTML block
• et_pb_sidebar → Widget block
• et_pb_gallery → Gallery block
• et_pb_counters → HTML approximation
• Fullwidth variants (et_pb_fullwidth_*) → full-width Group blocks

**Preserves:**

• All text content and inline HTML formatting
• Image URLs, alt text, and links
• Heading text and hierarchy
• Button labels, URLs, and targets
• Video URLs and embed sources
• List content
• Code block contents
• Basic color settings where Gutenberg supports them

What This Skill Does NOT Do

• **Divi's visual design layer** — Divi applies extensive CSS through its settings (gradient backgrounds, custom fonts from 800+ Google Fonts choices, box shadows with specific blur/spread, text shadow, filters, transforms). Gutenberg supports some of these; many will be simplified or lost.
• **Specialty sections** — Divi's specialty section layouts (sidebar + content combinations) have no direct Gutenberg equivalent.
• **Global modules** — Stored as `et_pb_layout` post type. These are resolved to inline content during migration; Gutenberg reusable blocks can be created manually afterward.
• **Divi Builder plugin modules** — Modules added by Divi-specific plugins (Divi Toolbox, Divi Supreme, etc.) are flagged.
• **Theme customizer settings** — Divi theme customizer values (global fonts, colors, sizing) don't transfer to block themes.
• **Dynamic content** — Divi's dynamic content features need separate solutions.
• **Contact forms** — et_pb_contact_form needs a forms plugin (WPForms, etc.).
• **Divi Library layouts** — Template library layouts stored in et_pb_layout post type are not auto-migrated.
• **Advanced design settings** — Rounded corners, CSS filters, blend modes, and transforms have limited Gutenberg support.

Requirements

• Respira for WordPress plugin installed and connected
• MCP connection active (desktop or WebMCP)
• Divi theme or Divi Builder plugin active (to read source content)
• WordPress 6.0+ (6.3+ recommended for Details block support)
• A block-compatible theme ready for post-migration (if switching from Divi theme)
• Read access to scan Divi content
• Write access to create duplicates with Gutenberg content

Trigger Phrase

• "migrate divi to gutenberg"

Alternative Triggers

• "convert divi to blocks"
• "switch from divi to gutenberg"
• "remove divi builder"
• "rebuild divi pages with blocks"
• "divi to block editor"
• "decommission divi"
• "get off divi"

Source Builder: Divi

Divi stores content as shortcodes in `post_content`. The module structure follows a strict hierarchy:

[et_pb_section fb_built="1" _builder_version="4.x"]
  [et_pb_row _builder_version="4.x"]
    [et_pb_column type="4_4" _builder_version="4.x"]
      [et_pb_text _builder_version="4.x"]
        <p>Your content here</p>
      [/et_pb_text]
      [et_pb_image src="image.jpg" alt="Alt text" _builder_version="4.x"][/et_pb_image]
      [et_pb_button button_text="Click Me" button_url="https://..." _builder_version="4.x"][/et_pb_button]
    [/et_pb_column]
  [/et_pb_row]
[/et_pb_section]

Key Divi specifics:

• **Section types**: regular, fullwidth, specialty (with predefined column layouts)
• **Column types**: defined by `type` attribute — `4_4` (full), `1_2` (half), `1_3` (third), `2_3` (two-thirds), `1_4` (quarter), `3_4` (three-quarters)
• **Settings as attributes**: `background_color`, `text_orientation`, `custom_margin`, `custom