Before the block editor, shortcodes were how WordPress added anything beyond plain text to content. Buttons, columns, tabs, accordions, galleries, pricing tables, testimonials and contact forms were all shortcodes. Themes shipped dozens of them. Plugins added more. Content teams memorised the syntax. Moving from shortcodes to blocks is worth it, but only with a plan.
Many sites still carry years of that legacy. I recently audited a site with over 2,000 posts containing 43 different shortcodes, some from a theme that had been replaced three years earlier and only kept active because removing it would break old posts.
Moving to blocks offers real benefits: visual editing instead of square brackets, better consistency, fewer theme dependencies and content that survives theme changes. But a careless migration can break hundreds of pages. This article covers how to plan it properly.
Why migrate at all
Shortcodes still work in the block editor, inside a Shortcode block or a Classic block. So why bother?
- Editing experience. Editors see [button url=”…” style=”primary”] instead of a button. Mistakes in syntax break output silently.
- Theme lock-in. Theme-provided shortcodes stop working when the theme changes, leaving raw brackets on the page.
- Consistency. Blocks use the theme’s design system. Old shortcodes often hard-code styles.
- Performance. Some shortcode libraries load CSS and JavaScript on every page, whether used or not.
- Future features. Block-based tools for patterns, styles and site editing don’t apply to shortcode output.
Step 1: Audit shortcode usage
You can’t plan a migration without knowing what you have. Start by listing every shortcode registered on the site and where each one is used.
To see registered shortcodes:
To count usage in content, search the posts table for each tag. A quick script helps:
Run it with wp eval-file. Also search postmeta and widget options, because page builders, custom fields and widgets often contain shortcodes too.
Then look for orphaned shortcodes: tags appearing in content that aren’t registered anymore. These already show as raw text on the front end:
That’s a rough search, so review the results by hand.
Step 2: Categorise
Sort the shortcodes into groups:
- Replaceable with core blocks. Buttons, columns, quotes, galleries, embeds, separators, spacers. Core blocks do these well.
- Replaceable with patterns or block styles. Callout boxes, testimonials, simple pricing tables. A Group block with a style or a synced pattern does the job.
- Needs a custom block. Shortcodes with dynamic data, like “latest products from category X”, or complex interactive features.
- Plugin shortcodes with block equivalents. Most form, gallery and WooCommerce plugins now offer blocks. Use those.
- Rarely used. A shortcode used in three posts may be easier to fix by hand.
- No longer needed. Some shortcodes can be removed entirely.
The count from your audit helps prioritise. A shortcode used in 800 posts justifies automated conversion. One used in five posts doesn’t.
Step 3: Build block equivalents
For each shortcode that needs a replacement, decide what the block version looks like. Wherever possible, use core blocks with styles or variations rather than custom blocks. They’re easier to maintain and work with future WordPress versions.
For custom blocks, keep attribute names close to the shortcode’s attributes. That makes conversion straightforward and reduces confusion for editors who knew the old syntax.
Step 4: Add block transforms
Blocks can define transforms, rules for converting other content into them. A shortcode transform lets the editor convert a shortcode into your block automatically. When someone opens an old post and converts the Classic block to blocks, the shortcode becomes the new block.
In a custom block’s registration:
Core blocks already include some shortcode transforms, such as
Transforms are great for gradual migration, because posts convert when someone edits them. They don’t help with the hundreds of posts nobody will ever open again.
Step 5: Bulk conversion
For bulk migration, you have two options.
Convert on the server
Write a script that parses post content, finds shortcodes and replaces them with block markup. Block markup is just HTML with comments:
The tricky part is that block markup must match exactly what the block’s save function produces, or the editor will show “This block contains unexpected or invalid content”. Generate a sample in the editor first, and match it precisely.
Use WordPress’s shortcode parsing functions, like get_shortcode_regex and shortcode_parse_atts, rather than writing your own regex. Shortcodes have edge cases, especially with nested and enclosing shortcodes.
Convert in the browser
Some tools run the editor’s own conversion in bulk: they load each post in a headless editor, convert Classic blocks to blocks using the registered transforms and save. This produces perfectly valid markup, because it uses the blocks’ own code. It’s slower but more reliable for complex content.
Whichever approach you choose, run it on staging first, check a sample of posts carefully and keep a full backup.
Step 6: Keep old shortcodes working
Even after migration, keep shortcode handlers registered for a while. Content might exist in places you didn’t convert: widgets, custom fields, email templates, cached content or posts you missed. If the old shortcode still renders, nothing breaks.
If the theme that provided the shortcodes is being replaced, move the shortcode functions into a small plugin first. That’s a quick, safe step on its own, because it separates content from theme before any conversion happens.
Notice the output uses modern block classes, so old shortcodes match the new design even before conversion.
Step 7: Check SEO and layout
After bulk conversion, check:
- Pages render as before, especially complex layouts like columns and tabs
- Internal links and anchor links still work
- Headings and structure haven’t changed in ways that affect SEO
- Structured data that shortcodes might have output, like FAQ schema, still appears
- No raw shortcode text appears on any page
A crawl with a tool like Screaming Frog, searching for “[” in page content, finds leftover shortcodes quickly.
Do it in phases
You don’t have to migrate everything at once. A sensible order:
- Move theme shortcodes into a plugin, so a theme change can’t break them.
- Stop using shortcodes for new content. Train editors on blocks.
- Convert the most-used shortcodes in bulk.
- Let the rest convert gradually as posts are edited, using transforms.
- After a year, check what remains and handle it manually.
Phased migration spreads the risk and the work, and it lets you learn from the first conversions before tackling the rest.
Communicating with the content team
Shortcode migrations affect editors more than developers. People who’ve used shortcodes for years have habits and shortcuts, and suddenly the familiar square brackets are replaced by blocks they haven’t used before.
Before migrating, run a short session showing editors how each old shortcode maps to its new block or pattern. Give them a one-page reference. After migration, ask them to report any page that looks wrong, with a simple way to do so, such as a shared form or a dedicated email address. Editors browse the site far more than developers do and will spot broken layouts quickly.
Also agree on a date after which new shortcodes shouldn’t be used. If someone keeps adding shortcodes to new posts out of habit, the migration never finishes.
Measuring progress
Rerun the audit script from the beginning every month or so. Seeing the count of shortcode uses fall from thousands to hundreds to dozens gives everyone a sense of progress and shows where to focus next. When a shortcode’s count reaches zero across all content types and meta, you can finally remove its handler and any assets it loaded, which is the moment the migration starts paying back in performance and simplicity.
Watch for shortcodes in unexpected places
Beyond post content, check menus, widget areas, theme options, WooCommerce product short descriptions, term descriptions and email templates. Shortcodes hide in all of these, and they’re often missed by content-only conversion scripts.
Keep a conversion log
Record which posts were converted, when and by which script. If a problem surfaces months later, the log tells you exactly which content to recheck and which backup to compare against. Moving from shortcodes to blocks is a marathon, not a sprint, and steady progress is what counts.
Frequently asked questions
Will migrating shortcodes affect my rankings?
Not if the rendered content stays the same. Search engines see the HTML output, not whether it came from a shortcode or a block.
What if a shortcode came from a plugin I still use?
Check whether the plugin now offers a block. Most popular plugins do. Converting to the plugin’s block is usually straightforward.
Can I just leave shortcodes in Classic blocks?
You can, and they’ll keep working as long as the shortcode is registered. Migration is about editing experience and long-term maintenance, not urgent breakage.
How do I handle nested shortcodes like columns inside tabs?
Convert from the inside out, and test carefully. Nested structures are where automated conversion most often goes wrong, so review those posts manually.





