# Migrate WPBakery to Gutenberg Converts WPBakery Page Builder (formerly Visual Composer) pages to native Gutenberg blocks. Parses WPBakery's shortcode-based content from post_content, maps each element 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 WPBakery to Gutenberg, eliminate the WPBakery dependency, switch to native blocks, or modernize an older WordPress site still running WPBakery. ## What This Skill Does WPBakery is one of the oldest and most widely-installed WordPress page builders — millions of sites still run it. It stores content as shortcodes in `post_content` using the `[vc_*]` prefix. The good news: WPBakery's shortcode structure is relatively straightforward compared to Divi's encoding complexities. The challenge: many WPBakery sites are older and may use deprecated elements, custom shortcodes from themes, or VC-specific plugins that add nonstandard elements. This skill parses the WPBakery shortcode tree, extracts content and settings, and generates equivalent Gutenberg blocks. The result is clean, modern WordPress content free from shortcode dependencies. **Handles:** - vc_row/vc_column → Columns and Column blocks - vc_column_text → Paragraph blocks (preserving HTML) - vc_single_image → Image block - vc_btn/vc_button → Buttons block - vc_video → Video or Embed block - vc_separator/vc_text_separator → Separator block - vc_empty_space → Spacer block - vc_row_inner/vc_column_inner → nested Columns blocks - vc_custom_heading → Heading block - vc_gallery/vc_images_carousel → Gallery block - vc_toggle → Details block (WP 6.3+) - vc_accordion/vc_accordion_tab → Group with Details blocks - vc_tabs/vc_tab → Group blocks with headings - vc_raw_html/vc_raw_js → Custom HTML block - vc_icon → Paragraph with icon (or HTML block) - vc_gmaps → Custom HTML block with embed - vc_progress_bar → HTML approximation - vc_wp_* widgets → corresponding WordPress widget blocks **Preserves:** - All text content and HTML formatting within vc_column_text - Image URLs, alt text, link targets - Heading text and hierarchy - Button labels, URLs, and basic styles - Video embed URLs - Gallery image collections - Code/HTML block contents - CSS classes applied via `el_class` attribute - Custom element IDs via `el_id` attribute ## What This Skill Does NOT Do - **Theme-bundled WPBakery elements** — Many themes add custom WPBakery elements (portfolio grids, team members, testimonial carousels, etc.). These are theme-specific and cannot be auto-mapped. They are flagged for manual recreation. - **WPBakery addons** — Ultimate Addons for WPBakery, Starter Templates, etc. add proprietary shortcodes that are flagged, not converted. - **vc_grid/vc_masonry_grid** — Post grid elements with complex query settings need manual recreation using Query Loop block or a posts plugin. - **Design options** — WPBakery's Design Options panel (accessed via `css` attribute containing encoded CSS) stores background, border, padding as a single encoded string. Basic properties are extracted; complex combinations may be simplified. - **Frontend editor layouts** — Some WPBakery designs rely on the frontend editor's pixel-precise positioning which has no block equivalent. - **WooCommerce elements** — vc_wp_product, cart, and checkout elements need WooCommerce blocks. - **Revolution Slider, Layer Slider** — Often bundled with WPBakery themes but are separate plugins. - **Templates** — WPBakery saved templates are not migrated as reusable blocks automatically. ## Requirements - Respira for WordPress plugin installed and connected - MCP connection active (desktop or WebMCP) - WPBakery Page Builder plugin active (to ensure shortcodes render/parse) - WordPress 6.0+ (6.3+ recommended for Details block) - A block-compatible theme (often needed since WPBakery sites tend to run older themes) - Read access to scan WPBakery content - Write access to create duplicates with Gutenberg content ## Trigger Phrase - "migrate wpbakery to gutenberg" ## Alternative Triggers - "convert wpbakery to blocks" - "switch from wpbakery to gutenberg" - "migrate visual composer to gutenberg" - "remove wpbakery" - "rebuild wpbakery pages with blocks" - "wpbakery to block editor" - "decommission wpbakery" - "get rid of visual composer" ## Source Builder: WPBakery WPBakery stores content as shortcodes in `post_content`: ``` [vc_row full_width="stretch_row" css=".vc_custom_123{padding-top:40px}"] [vc_column width="1/2" el_class="my-class"] [vc_column_text]

Welcome

Content with formatting.

[/vc_column_text] [vc_single_image image="456" img_size="large" alignment="center"] [/vc_column] [vc_column width="1/2"] [vc_btn title="Learn More" style="flat" color="primary" link="url:https%3A%2F%2Fexample.com"] [/vc_column] [/vc_row] ``` Key WPBakery specifics: - **Row/column structure**: `[vc_row]` → `[vc_column width="1/2"]` → elements - **Column widths as fractions**: `1/1`, `1/2`, `1/3`, `2/3`, `1/4`, `3/4`, `1/6`, `5/6` - **Inner rows**: `[vc_row_inner][vc_column_inner]` for nested layouts - **CSS attribute**: Encoded CSS from Design Options panel — e.g., `css=".vc_custom_12345{background-color:#f5f5f5;padding:20px}"` - **Link encoding**: URLs in button/link elements use percent-encoding — `url:https%3A%2F%2F...||target:_blank` - **Full-width modes**: `full_width` attribute: `stretch_row`, `stretch_row_content`, `stretch_row_content_no_spaces` - **Element classes**: `el_class` for custom CSS classes, `el_id` for IDs - **Templates**: Saved as separate post type, referenced by ID Read WPBakery content via `wordpress_extract_builder_content` with `builder=wpbakery`. ## Target: Gutenberg (Block Editor) Gutenberg stores content in `post_content` as HTML with block delimiters: ```html

Welcome

Content with formatting.

``` Key Gutenberg specifics: - Block attributes in opening comment JSON - Column widths as percentages - Inline styles via `style` attribute - Everything in `post_content` Write Gutenberg content via `wordpress_update_page` or `wordpress_update_post` targeting the `content` field. ## 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. Confirm WPBakery is active via `wordpress_list_plugins`. 3. Check WordPress version (6.0+ required, 6.3+ ideal). 4. Identify active theme — note if it bundles WPBakery and adds custom elements. 5. Scan all content for WPBakery usage: - `wordpress_list_pages` and `wordpress_list_posts` - Check builder via `wordpress_get_builder_info` 6. Extract WPBakery content via `wordpress_extract_builder_content` with `builder=wpbakery` 7. Build inventory: - Total pages/posts using WPBakery - Element types used (frequency count) - Theme-specific custom elements (flagged) - Third-party addon elements (flagged) - vc_grid/masonry elements (flagged) - Design Options CSS complexity - Complexity per page (simple/moderate/complex) - Encoded links that need decoding ### Phase 2: Migration Plan ``` ## WPBakery → Gutenberg Migration Plan ### Site Context WPBakery sites are often older WordPress installations. Consider this migration as a modernization opportunity — not just a builder swap. ### Theme Note [If theme bundles WPBakery]: Your theme ([theme name]) bundles WPBakery and likely adds custom elements. These theme-specific elements (X found) will need manual recreation. Consider whether this theme should also be updated to a modern block theme. ### Site Inventory - Total WPBakery pages: X - Total elements to convert: X - Direct block equivalents: X (Y%) - Approximate equivalents: X (Y%) - Manual recreation needed: X (Y%) ### Element Mapping Summary | WPBakery Element | Gutenberg Block | Fidelity | |--------------------|-----------------|-----------| | vc_column_text | wp:paragraph | Exact | | vc_single_image | wp:image | Exact | | vc_custom_heading | wp:heading | Exact | | vc_btn | wp:buttons | Close | | vc_row/vc_column | wp:columns | Close | | vc_gallery | wp:gallery | Close | | vc_toggle | wp:details | Close | | vc_grid | wp:query | Manual | | [theme element] | — | Manual | ### Design Options Analysis - Pages with simple Design Options: X (colors and padding — auto-mapped) - Pages with complex Design Options: X (gradients, borders — partially mapped) ### Page-by-Page Plan 1. **[Page Title]** — X elements, [complexity] 2. ... ``` Ask for confirmation: > WPBakery → Gutenberg is a modernization step. Pages will be cleaner and faster. > 1. Migrate all pages > 2. Migrate specific pages > 3. Start with a test page (recommended for sites with theme-bundled elements) > 4. Just keep this plan ### Phase 3: Page-by-Page Migration For each approved page: 1. Read WPBakery content via `wordpress_extract_builder_content` with `builder=wpbakery` 2. Parse the shortcode tree: - Identify vc_row → vc_column → element hierarchy - Decode CSS from Design Options attribute - Decode link URLs from WPBakery's percent-encoding format - Handle vc_row_inner/vc_column_inner nesting 3. Map each element: - `vc_row` → `` (check `full_width` for alignment) - `vc_column` → `` (convert fractions: 1/2→50%, 1/3→33.33%, etc.) - `vc_column_text` → Parse inner HTML, split into appropriate blocks: - `

` → `` - `

` → `` - `