WordPress shortcode cleanup after a migration

Shortcodes are WordPress's oldest composition layer — [gallery], [caption], and thousands of plugin-specific tags that render content at parse time. Page builders leaned on them heavily: Divi, WPBakery, Flatsome UX Builder, Avada Fusion, and Thrive all store layouts as shortcode strings. After you migrate to ACF blocks and deactivate the old stack, any shortcode the new site doesn't register either shows as raw text on the page or disappears entirely. Cleanup is the forensic pass that finds what's left.

Why shortcodes survive migration

• arrow_rightPartial migration: some pages were rebuilt in blocks; others were 'good enough' and skipped.
• arrow_rightWidget areas and sidebars: old shortcodes in Text widgets don't appear in post crawls.
• arrow_rightACF fields: a WYSIWYG or textarea sub-field can contain shortcodes invisible to the main editor view.
• arrow_rightReusable blocks and synced patterns imported from the old site.
• arrow_rightBlog posts nobody reviewed because 'posts migrate fine' — but posts had builder shortcodes too.
• arrow_rightTheme options that inject shortcodes into headers/footers via hooks.

How to find every shortcode on the site

Database search

Search wp_posts.post_content and wp_postmeta.meta_value for the pattern [ — tools like Better Search Replace or an SQL LIKE query on staging. Also search wp_options for theme_mods and widget entries. This catches stored shortcodes even on unpublished drafts.

Front-end crawl

Crawl the rendered site and search for literal bracket strings in the HTML output — [vc_row], [et_pb_line], [ux_banner] appearing as visible text means the shortcode wasn't processed. Also look for empty containers where a shortcode rendered nothing.

Plugin audit

List every plugin that registered shortcodes on the old site. Common survivors: contact-form-7, gravityform, embed shortcodes, gallery plugins, and custom theme shortcodes. Decide which plugins stay on the new site (and re-register their shortcodes) vs which need content rebuilt in blocks.

Cleanup strategies by shortcode type

The regex trap

It's tempting to run a global regex that strips everything matching [.*?] from the database. Don't — at least not without a backup and a human review pass. Nested shortcodes, legitimate bracket characters in code samples, and JSON in block attributes can all match naive patterns. Shortcode cleanup is a find-and-replace job with judgement, not a one-line sed command.

A structured cleanup workflow

1. 1Inventory: database + crawl search; group by shortcode prefix ([et_pb_, [vc_, [ux_, [fusion_, etc.).
2. 2Prioritise: indexable pages with traffic first; drafts and orphaned pages last.
3. 3Replace: for each group, either migrate content into the correct ACF block or install the plugin that registers the shortcode.
4. 4Verify: re-crawl after cleanup; zero visible bracket strings on public pages.
5. 5Deactivate: remove old builder plugins only when their shortcode prefix returns zero hits in the database.

Prevention on the next rebuild

The reason agencies migrate to ACF blocks is partly shortcode elimination — field-driven blocks don't use shortcodes in post_content. A complete crawl-and-map migration from the rendered page replaces builder shortcodes with Gutenberg block comments in post_content. If you're still finding builder shortcodes after migration, some pages weren't in the crawl scope — check your include/exclude path filters and sitemap coverage.

Related: Divi migration, WPBakery migration, Flatsome migration, and the migration QA checklist which includes a shortcode debris check on every template.

WP-CLI and scripted shortcode audits

On staging, wp db search 'et_pb_' --all-tables surfaces Divi debris across postmeta. Repeat for vc_, ux_, fusion_, tcb_. Export results to CSV grouped by post ID. Developers can script reports: post URL, shortcode prefix, last modified — editors work from a prioritised queue instead of random spot-checks.

When shortcode cleanup should block launch

Visible [vc_row] or [et_pb_section] on the homepage or top five organic landing pages blocks launch. Raw shortcodes in legal or pricing pages block launch. Shortcodes inside an old blog post ranking on page four can wait — document in post-launch backlog. Client-facing criterion: no visitor-visible bracket strings on money pages.

Documenting cleanup for handover

Leave the client a shortcode inventory spreadsheet: prefix, count, resolution (migrated, plugin kept, retired). Future developers searching for et_pb_ in the database will understand what was intentional versus overlooked debris.

Shortcodes in widget areas and theme mods

Text widgets in legacy sidebars and footers often hold [contact-form-7] or custom theme shortcodes — they do not appear in page crawls. Export widget settings from the old site and rebuild sidebar/footer content in block-based widget areas on the new theme before assuming cleanup is complete.

Shortcodes hiding in block attributes and patterns

Gutenberg block comments can contain shortcode strings inside block attributes — especially after importing old reusable blocks or running a partial WXR import alongside ACF migration. Core HTML blocks, Classic blocks, and custom HTML blocks are common hiding places. Search post_content for [ in the database after migration, not only visible front-end output. Block editor preview may render shortcodes if the registering plugin is still active, masking debris until you deactivate the old builder.

• arrow_rightSearch wp_posts.post_content for [et_pb_, [vc_, [ux_, [fusion_, [tcb_ after import.
• arrow_rightCheck wp_posts.post_content for wp:block comments containing shortcode strings.
• arrow_rightInspect synced patterns and reusable blocks in WordPress admin — not just pages.
• arrow_rightReview template parts and FSE templates if the new theme uses block themes.

Legitimate shortcodes to keep versus builder debris

Not every shortcode should die on migration. Forms ([gravityform id="1"]), embeds ([embed]), and gallery shortcodes from plugins you intend to keep are valid. Builder layout shortcodes ([vc_row], [et_pb_section]) are debris. Maintain an allowlist spreadsheet: prefix, keep or remove, replacement block or plugin. Editors and future developers use this during QA and handover.

Widget block areas and legacy sidebars

Block-based widget areas replaced classic Text widgets on modern themes, but migrated databases often still carry widget entries in wp_options under sidebars_widgets and widget_text. Export and inspect widget settings from the old site. Footer phone numbers, social icons, and newsletter shortcodes frequently live here. Rebuild in footer template parts or block-based footer widget areas — then remove orphaned widget options to prevent confusion on future imports.

Automating shortcode reports without destructive regex

WP-CLI wp db search 'vc_row' --all-tables exports every hit with table name and row context. Run per prefix on staging; pipe results to CSV grouped by post ID. Developers script weekly reports during cleanup sprints; editors work from a queue sorted by traffic tier. Never run global DELETE or blind regex replace on production — nested shortcodes and JSON in block attributes false-positive on naive patterns.

1. 1Generate prefix report CSV — post URL, prefix, hit count.
2. 2Sort by Analytics sessions descending.
3. 3Migrate or replace top 50 URLs first.
4. 4Re-run report until builder prefixes hit zero on indexable content.
5. 5Deactivate old builder; re-crawl for visible bracket strings.
6. 6Sign off in migration QA checklist shortcode debris section.

Post-launch shortcode monitoring

Clients edit content after handover and sometimes paste from old pages in email archives — reintroducing builder shortcodes. Include shortcode awareness in editor training: 'If you see square brackets in the preview, stop and ask.' Quarterly crawl for bracket strings on high-traffic pages catches regression before Search Console does.