Block Migration Tool

Swap one block for another across your whole site and keep its content.

Lauren Gray Avatar

Block Migration Tool swaps one block for another across your whole site and carries the old block’s content into the new one. It’s handy after a theme change, or when you’re retiring a block plugin.

Before you start

  • WordPress 5.8 or later
  • PHP 7.0 or later
  • An administrator account (the tool needs the manage_options capability)
  • A fresh backup. Migrations rewrite post content directly, and there’s no undo button.

Install

  1. In your dashboard, go to Plugins → Add New Plugin.
  2. Click Upload Plugin and choose the plugin zip file.
  3. Click Install Now, then Activate.

How to use

Run a migration

  1. Go to Block Migration in the admin menu.
  2. In Target block, enter the name of the block you want to replace, such as core/paragraph or my-plugin/old-callout.
  3. Optionally, pick a Post type and choose specific posts in Select posts. Leave Select posts empty to migrate every post.
  4. In Source block, write the markup for the new block. Use template tags such as {{ attrs.title }} to pull in the old block’s values. (More on templates below.)
  5. Adjust Batch size if needed. It sets how many posts are processed per request.
  6. Click Run Migration. A progress bar shows “Processing: X% complete”, and you’ll get a “Migration completed successfully!” alert when it’s done.

Tip: try it first on one test post by picking just that post in Select posts. Then check the result in the editor before running it site-wide.

What gets migrated

  • Which posts: with no posts selected, the tool works through every public post type except media attachments. It includes published, scheduled, draft, pending and private posts, but not trashed ones.
  • Which blocks: every block whose name exactly matches Target block, including blocks nested inside other blocks.
  • One block out: only the first block in your Source block template is used. If the replacement needs several blocks, wrap them in one container block, such as a Group.

Write a source block template

The Source block field uses Twig 2.x syntax. It has syntax highlighting and autocomplete: type { to get snippets, or press Ctrl+Space for suggestions.

  • {{ ... }} outputs a value
  • {% ... %} adds logic: if, for, set and more
  • {# ... #} is a comment that’s left out of the output

The old block’s attributes are available as attrs. Use dot notation for nested values, like {{ attrs.image.url }}.

<!-- wp:heading -->
<h2 class="wp-block-heading">{{ attrs.title }}</h2>
<!-- /wp:heading -->

Show something only when a value is set:

{% if attrs.showTitle %}
<!-- wp:heading -->
<h2 class="wp-block-heading">{{ attrs.title }}</h2>
<!-- /wp:heading -->
{% endif %}

Loop over a list attribute:

<!-- wp:list -->
<ul class="wp-block-list">
{% for item in attrs.items %}
<!-- wp:list-item --><li>{{ item.label }}</li><!-- /wp:list-item -->
{% endfor %}
</ul>
<!-- /wp:list -->

Some blocks keep their content in the block’s HTML instead of its settings. A core paragraph’s text is one example. The tool reads those values too, but it only gets the plain text, so inline formatting like bold or links isn’t carried over.

Built-in functions

You can use these inside {{ }} and nest them, like {{ nl2br(strip_comments(attrs.content)) }}.

  • nl2br(value): turns line breaks into <br> tags.
  • autop(value): wraps text in paragraphs using WordPress’s wpautop(). Images on their own aren’t wrapped.
  • strip_comments(value): removes HTML comments, including block comment delimiters.
  • convert_to_blocks(value): turns raw HTML into real block markup. Existing blocks stay as they are, and if conversion fails, the original HTML is kept.
  • img_url(attachment_id): the full URL of a media library image, or empty if none is found.
  • get_post_title(post_id): a post’s title, or empty if none is found.
  • get_post_excerpt(post_id): a post’s excerpt. If there’s no manual excerpt, you get the first 55 words of the content. Empty if no post is found.

Settings

  • Batch size: posts processed per request, from 1 to 100. Default is 10. Lower it if your host times out.
  • Target block: the exact name of the block to replace (namespace/name).
  • Post type: which post type to search in Select posts. Changing it clears your selected posts.
  • Select posts: limit the migration to specific posts. Leave it empty to migrate everything.
  • Source block: the Twig template for the replacement block.

Settings aren’t saved. Copy your template somewhere safe if you plan to reuse it.

Developer reference

For developers: hooks and functions you can use from your theme or a code snippet.

block_migration_tool_twig_functions

Filter. Adds your own functions to the Twig templates you write for replacement blocks. Receives an array of \Twig\TwigFunction objects.

add_filter( 'block_migration_tool_twig_functions', function ( $functions ) {
	$functions[] = new \Twig\TwigFunction( 'slugify', 'sanitize_title' );
	return $functions;
} );

Then use it in a template: {{ slugify( attrs.title ) }}.

block_migration_tool_before_migration_post_content

Filter. Changes a post’s raw content before its blocks are parsed and migrated. Receives the post content as a string.

block_migration_tool_excluded_post_types

Filter. Hides post types from the migration screen. Receives an array of post type names. Defaults to array( 'attachment' ).

add_filter( 'block_migration_tool_excluded_post_types', function ( $excluded ) {
	$excluded[] = 'wp_block';
	return $excluded;
} );

FAQs

My old templates stopped working after updating

Version 1.0.3 switched templates to Twig. Update the old syntax like this:

  • {{$attrs.field}} → {{ attrs.field }}
  • {{post-title:$attrs.postId}} → {{ get_post_title(attrs.postId) }}
  • {{post-excerpt:$attrs.postId}} → {{ get_post_excerpt(attrs.postId) }}
  • {{img-url:$attrs.imageId}} → {{ img_url(attrs.imageId) }}
  • {{nl2br($attrs.content)}} → {{ nl2br(attrs.content) }}
  • {{autop($attrs.content)}} → {{ autop(attrs.content) }}
  • {{stripComments($attrs.content)}} → {{ strip_comments(attrs.content) }}
  • {{convertToBlocks($attrs.content)}} → {{ convert_to_blocks(attrs.content) }}
Does it work with WP Recipe Maker?

When WP Recipe Maker is active, the tool first converts WPRM’s fallback recipe markup back to its shortcode before migrating, so the block parser can read the post.

Can developers customize it?

Yes, with three filters:

  • block_migration_tool_excluded_post_types: post types to skip. Default is attachment.
  • block_migration_tool_twig_functions: add your own Twig functions.
  • block_migration_tool_before_migration_post_content: adjust post content before it’s parsed.