Tutorial

Cleaning up legacy shortcodes: migrating from page builders to block patterns

A step-by-step agency guide to identifying legacy page builder shortcodes, cleaning wp_posts content, and replacing brittle layouts with core block patterns.

To move a site off a page builder safely, work on staging: audit which shortcodes and postmeta the builder left, hide the leftover shortcodes, rebuild each page with core block patterns, then clean out the old data before you switch.

When an agency inherits a legacy WordPress website built on WPBakery, Divi, or early versions of Elementor, the database is typically crowded with proprietary shortcodes and serialised JSON blobs. Deactivating the old builder plugin leaves raw tags like [vc_row], [vc_column], and [et_pb_section] exposed directly on published pages, producing broken layouts and unformatted text strings on the front end.

Rebuilding every page manually from scratch is rarely feasible on tight client budgets. A disciplined, systematic migration workflow allows you to audit existing database records, safely suppress orphaned shortcodes during staging, clean out legacy postmeta, and replace fragile builder widgets with durable core block patterns.

Auditing the database for legacy builder footprints#

Before touching code or deactivating plugins on a staging environment, query the wp_posts table to quantify which shortcodes are present and determine how many records are affected.

Using WP-CLI on your staging server:

# Search for WPBakery shortcodes across published pages
wp db query "SELECT ID, post_title FROM wp_posts WHERE post_content LIKE '%[vc_%' AND post_status = 'publish' AND post_type = 'page';"

# Search for Divi builder shortcodes
wp db query "SELECT ID, post_title FROM wp_posts WHERE post_content LIKE '%[et_pb_%' AND post_status = 'publish' AND post_type = 'page';"

# Search for Elementor post records
wp db query "SELECT post_id FROM wp_postmeta WHERE meta_key = '_elementor_edit_mode' AND meta_value = 'builder';"

Export this list of post IDs to establish your migration checklist. Group the URLs by template archetype (homepage, standard service pages, case study layouts, contact pages) so you can replace recurring widget layouts with a consistent set of block patterns.

Safely suppressing orphaned shortcodes during migration#

If you deactivate a page builder without first cleaning its shortcodes, WordPress ignores unrecognised tags and prints them verbatim to visitors.

To maintain readable content on staging while pages are actively converted, register a temporary fallback filter in an mu-plugin (wp-content/mu-plugins/shortcode-cleaner.php):

<?php
/**
 * Plugin Name: Safe Migration Shortcode Fallback
 * Description: Suppresses orphaned builder shortcodes while preserving inner content.
 */
add_action( 'init', function () {
    $orphaned_shortcodes = array(
        'vc_row', 'vc_column', 'vc_column_text', 'vc_section',
        'et_pb_section', 'et_pb_row', 'et_pb_column', 'et_pb_text'
    );

    foreach ( $orphaned_shortcodes as $tag ) {
        if ( ! shortcode_exists( $tag ) ) {
            add_shortcode( $tag, function ( $atts, $content = '' ) {
                return do_shortcode( $content );
            } );
        }
    }
} );

This helper executes any nested shortcode content while stripping away the enclosing structural wrapper tags, allowing the underlying text and media to render without raw shortcode brackets cluttering the canvas.

Replacing legacy widgets with modern block sections#

Legacy visual builders usually structure pages around predictable layout archetypes: oversized hero sliders, three-column feature cards, client quote bands, and call-to-action footers.

Instead of writing custom block code for every individual layout, map each legacy component to a standard core block pattern:

Legacy builder componentNative core block equivalent
Full-width banner or sliderwp:cover with nested wp:heading and wp:buttons
3-column feature grid ([vc_row])wp:columns with 3 wp:column containers
Testimonial sliderwp:quote or styled wp:group cards
Pricing table widgetwp:columns with nested semantic lists and buttons
Accordion FAQ widgetNative wp:details disclosure blocks

Replacing a legacy hero slider with a clean, semantic composition improves initial page load times dramatically while eliminating third-party JavaScript dependencies.

Here is an example of an editorial hero composition that provides visual character and motion without relying on heavy page builder slider runtimes:

Live patternThe Dispatch: Editorial magazine hero replacing legacy sliders
Open full ↗
Try dragging the comparison handle. Toggle between Designed (curated typography and palette) and Use my theme to see how the layout automatically adapts to theme tokens.

Step-by-step page conversion workflow#

For each page on your migration checklist, follow this structured conversion process:

  1. Open the page in the block editor: With your mu-plugin active, the editor displays the raw text within legacy shortcode containers.
  2. Insert the replacement pattern: Paste the corresponding block pattern onto the editor canvas immediately below the legacy section.
  3. Migrate text and media: Copy the headline, body copy, and button destination from the legacy shortcode markup into the pattern blocks. Re-select images from the media library to ensure core responsive srcset attributes are generated.
  4. Delete the legacy shortcode container: Remove the old shortcode block completely, leaving only clean core block comments in the document.
  5. Verify List View: Check the editor List View to confirm that the new section uses clean container nesting and semantic heading tags.

Handling responsive columns and image aspect ratios#

A subtle pitfall during builder migrations is column stacking behaviour. Page builders often rely on proprietary JavaScript breakpoints to stack columns at arbitrary viewport widths like 992px or 768px.

In core WordPress, wp:columns handles responsive stacking automatically via CSS flexbox:

<!-- wp:columns {"isStackedOnMobile":true} -->
<div class="wp-block-columns is-stacked-on-mobile">
  <!-- wp:column -->
  <div class="wp-block-column"><!-- content --></div>
  <!-- /wp:column -->
</div>
<!-- /wp:columns -->

When migrating three-column card grids, ensure each card image uses a consistent core block aspectRatio property (such as 16/9 or 4/3) rather than fixed pixel heights. This guarantees that replacement images scale smoothly across mobile devices without distorted crops or unwanted letterboxing.

Cleaning orphaned metadata from wp_postmeta#

Visual builders do not store all their data in post_content. Elementor, for instance, stores its primary layout JSON in the _elementor_data postmeta key, while Divi and Beaver Builder store custom CSS strings and module configurations across multiple metadata rows.

Leaving thousands of orphaned postmeta rows bloats the wp_postmeta table and slows down WordPress autoload queries.

Once all pages have been converted to core blocks, clean up leftover metadata using WP-CLI:

# Delete Elementor layout payloads from converted posts
wp db query "DELETE FROM wp_postmeta WHERE meta_key IN ('_elementor_data', '_elementor_css', '_elementor_version', '_elementor_edit_mode');"

# Delete Divi custom styling metadata
wp db query "DELETE FROM wp_postmeta WHERE meta_key LIKE '_et_pb_%';"

Always run a full database backup (wp db export backup-pre-clean.sql) before executing raw DELETE queries.

Final production verification#

Before launching the migrated block site to production:

  1. Run a database audit for remaining shortcodes: Verify that your original wp db query returns zero rows across all published posts.
  2. Deactivate and remove builder plugins: Deactivate the legacy builder plugin and your temporary shortcode suppression mu-plugin. Confirm that all pages load with zero PHP warnings or unparsed shortcodes.
  3. Audit Core Web Vitals: Run Lighthouse or WebPageTest against key templates. Removing builder framework CSS and JavaScript typically reduces total blocking time (TBT) by 200ms to 600ms and cuts page weight by more than half.
  4. Purge caching layers: Clear persistent object caches and edge CDN caches (wp cache flush) to ensure visitors receive clean, modern HTML markup.

Pattern Paste makes migrating away from visual page builders straightforward by providing 542 ready-to-paste core block patterns for heroes, feature grids, pricing tables, and footers. Explore the catalogue to see Core Patterns that inherit your theme and Interactive Patterns with curated styling.

From the library

The patterns in this post.

Keep reading.

All 16 articles

8 Themes · 542 patterns · 58 interactive

Your next site, finished sooner.

Start a whole site from a theme, or add one section to the site you have.

Browse themesSubscribe