Convert Classic WordPress Content to Blocks

An old post can look perfectly fine on the public site while feeling awkward inside the Block Editor: the entire article sits inside one Classic block, headings are hard to move, and media cannot use modern layout controls. Converting it can make future editing much nicer, but the page’s current appearance is part of the contract. Preserve that contract while improving the editing structure.

Know what is being converted

• Classic Editor content is ordinary HTML stored in post_content, often with shortcodes and plugin markup.

• When opened in the Block Editor, legacy content may be wrapped in a single core/freeform Classic block.

• Convert to blocks applies raw HTML transformations to create paragraph, heading, list, image, quote, and other recognized blocks.

• WordPress blocks are still serialized into post_content as HTML plus <!-- wp:... --> comment delimiters.

• Conversion changes editing structure; it does not automatically modernize the theme, templates, CSS, accessibility, or old plugin output.

Do not confuse three different migrations

• Classic post content → individual content blocks is the task covered here.

• Classic theme → block theme is a site-template architecture project and is not required to edit posts as blocks.

• Classic Editor plugin → Block Editor changes which editor opens; it does not guarantee every legacy document is decomposed into blocks.

• A post can remain in a Classic block indefinitely if conversion would damage a complex layout.

• A Custom HTML or Shortcode block may be the correct destination for markup that has no safe core-block transform.

Create a rollback point first

$ mkdir -p migration-backups
wp db export migration-backups/before-classic-to-blocks.sql
wp export --post_type=post,page --dir=migration-backups

Success: Exported to migration-backups/before-classic-to-blocks.sql
Starting export process...
... All done with export.

A backup is useful only if it can be restored

• wp db export snapshots the database, including content and site configuration, to the chosen file.

• wp export creates WordPress eXtended RSS files for content-level portability; it is not a complete replacement for a database and media backup.

• Store backups outside the public web root, restrict access, encrypt them where required, and apply a retention policy.

• Back up wp-content/uploads and relevant plugin/theme code through the site’s normal backup system.

• Test restoration on staging before beginning a large migration.

Choose a representative pilot post

• Start with a published, low-traffic post containing headings, lists, links, images, captions, and at least one legacy shortcode.

• Capture full-page desktop and mobile screenshots before editing.

• Record the post ID, URL, current revision, author, modified time, and plugins that render its shortcodes.

• Run an accessibility/performance baseline if the page is commercially important.

• Avoid beginning with the homepage, highest-traffic landing page, checkout flow, or a page-builder document.

Convert one Classic block

1. Open the post or page in the WordPress Block Editor.

1. Confirm the content appears inside a Classic block rather than as already separated blocks.

1. Select the Classic block; use its toolbar or three-dot options menu and choose “Convert to blocks.”

1. Open Document Overview/List View and inspect the resulting hierarchy.

1. Save as a draft or use Preview first; do not immediately update the published page.

Review structure before appearance

• Exactly one page title/H1 should normally come from the theme/template; article sections should begin at H2.

• Headings must be real Heading blocks in a logical hierarchy, not bold Paragraph blocks.

• Lists should be List blocks with properly nested list items.

• Images should retain attachment, alt text, caption, link target, size, alignment, and aspect ratio.

• Quotes, tables, embeds, galleries, buttons, code, separators, and footnotes need the correct semantic block.

• Empty paragraphs and spacer markup should not be used to imitate layout that belongs in CSS/block spacing.

Treat shortcodes as application dependencies

• A shortcode may remain in a Shortcode block; that is not necessarily a failed conversion.

• Identify which plugin or theme registers every shortcode and whether it is still maintained.

• Preview while the dependency is active and test the failure behavior when it is absent.

• Do not paste rendered shortcode HTML back into the post unless you deliberately want a static snapshot.

• Replace obsolete shortcodes gradually with supported blocks or server-rendered alternatives, preserving data and URLs.

Inspect custom HTML without sanitizing it by accident

• Tables, iframes, scripts, forms, inline styles, microdata, and custom classes may remain in a Custom HTML block.

• User roles without unfiltered_html can have disallowed markup removed on save.

• A block transform can rearrange invalid or malformed legacy HTML because the browser/parser repairs it.

• Move reusable design rules to theme/plugin CSS instead of duplicating inline style across hundreds of posts.

• Never bulk-strip comments: WordPress block delimiters are HTML comments and carry block identity/attributes.

Compare rendered output, not editor canvas alone

• Preview the exact post with the production theme and active plugins.

• Compare desktop, tablet, and narrow mobile widths against pre-conversion screenshots.

• Check links, anchors, downloads, image lightboxes, galleries, embeds, forms, code wrapping, tables, and captions.

• Inspect browser console errors, failed network requests, layout shifts, and unexpected horizontal overflow.

• Verify structured data, table of contents, related-post extraction, ads, analytics, and newsletter placements that parse post markup.

• Run keyboard and screen-reader spot checks on headings, links, images, tables, and interactive blocks.

Use revisions as a second rollback layer

• WordPress creates a revision when a post is saved if revisions are enabled.

• Open the Post/Page settings sidebar and select the Revisions count to compare saved versions.

• Restore the pre-conversion revision if the new structure cannot be repaired safely.

• Autosaves do not replace a database backup and may be pruned by configuration or hosting policy.

• On WordPress 7.0 the revisions interface changed; earlier versions show the classic revision comparison screen.

Audit serialized content carefully

$ POST_ID=123
wp post get "$POST_ID" --field=post_content > /tmp/post-content.html
grep -n '<!-- wp:' /tmp/post-content.html | head
grep -nE '[[A-Za-z_][A-Za-z0-9_-]*([^]]*)]' /tmp/post-content.html | head

1:<!-- wp:paragraph -->
...
42:[gallery ids="10,11"]

This audit finds clues, not proof

• Replace 123 with one reviewed post ID; the commands are read-only.

• Block delimiter matches show serialized block structure but do not prove every block is valid.

• The shortcode pattern can produce false positives in prose, code, and attributes; review each match manually.

• parse_blocks() is the supported PHP parser when automation needs structural analysis.

• Do not transform database content with grep, sed, or regular expressions.

Why blind bulk conversion fails

• HTML parsing is contextual; regex cannot reliably model nested markup, malformed legacy HTML, or embedded scripts.

• Custom blocks may be unavailable on the migration environment and become “missing” or invalid.

• Dynamic shortcodes depend on plugin state and external services.

• Theme CSS may target old classes or raw elements and not equivalent core-block wrappers.

• Post-specific metadata, reusable blocks, galleries, attachment links, and page-builder records can live outside the visible HTML.

• A bulk database update can bypass revisions, cache invalidation, hooks, audit trails, and editorial review.

If automation is necessary

• Inventory content types and patterns first; classify simple, complex, builder-owned, and exception posts.

• Use WordPress block parsing/serialization APIs in a version-controlled migration plugin or WP-CLI command.

• Make the operation idempotent: a second run must not wrap or duplicate blocks.

• Store the original post_content, post ID, checksum, transformation version, result, and errors.

• Dry-run and diff without writing, then process a tiny batch with per-post transactions/rollback strategy.

• Render-test samples and stop automatically on invalid blocks, missing shortcodes, or unexpected structural changes.

• Keep canonical URLs, authorship, dates, taxonomies, comments, and media relationships unchanged unless separately planned.

Publishing without unnecessary SEO movement

• Do not change the slug merely because editing structure changed.

• Retain heading meaning, internal links, image URLs/alt text, canonical metadata, and structured-data inputs.

• Avoid changing published time; update modified time only when the content substantially changes.

• Purge page/CDN caches after publishing and confirm the canonical URL returns the expected status.

• Compare rendered text and metadata so conversion does not silently remove indexable content.

• Monitor Search Console, analytics, error logs, and Core Web Vitals after each batch.

A humane migration cadence

• Convert one post, review it, publish it, and observe it before increasing batch size.

• Keep an exception list for documents that should remain Classic or require specialist reconstruction.

• Give editors a short block-writing standard for headings, images, links, code, tables, and reusable patterns.

• Track post ID, owner, backup, conversion status, review status, visual diff, errors, publish time, and rollback result.

• Audit taxonomy and internal links during content improvement, but do not turn a format migration into an uncontrolled redesign.

When leaving a post in Classic is reasonable

Conversion is optional, not a badge of quality. A stable legacy page can remain inside a Classic block when a page builder owns it, a retired shortcode must be preserved, or reconstruction costs more than future editing will save. Document the exception and keep its dependencies maintained.

Final pre-publish check

• Backup and pre-conversion screenshot exist.

• List View shows sensible blocks and heading hierarchy.

• No invalid or unexpectedly recovered blocks remain.

• Shortcodes, embeds, custom HTML, links, and media behave correctly.

• Desktop/mobile visual comparison passes.

• Accessibility, metadata, analytics, ads, and performance integrations still work.

• A revision or tested backup can restore the original.

• A second editor has reviewed high-value pages.

Primary references

• WordPress explains how the Block Editor works with blocks and exposes transforms through each block’s toolbar.

• The Block Editor Handbook documents serialized block data flow and why HTML comment delimiters are part of the stored format.

• The official parser documentation explains how saved HTML is parsed into block structures.

• WordPress’s revisions documentation covers comparison, restore behavior, autosaves, and version-specific interfaces.