/migrate-wpbakery-to-gutenberg

name: migrate-wpbakery-to-gutenberg
description: "Use when the user says 'migrate wpbakery to gutenberg', 'remove wpbakery', 'get rid of visual composer', or 'decommission wpbakery'. Parses WPBakery shortcodes, 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 WPBakery 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 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]
      <h2>Welcome</h2>
      <p>Content with <strong>formatting</strong>.</p>
    [/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`,