How to Convert Classic Editor Content Into Blocks

Back up WordPress, create staging, and convert one representative Classic block. Inspect the resulting blocks before saving or scaling.

Use the Classic block’s Convert to blocks action. Then repair headings, lists, media, shortcodes, custom HTML, and page-specific settings.

Stable legacy content can remain classic temporarily. Conversion should solve editing or maintenance problems, not satisfy architectural tidiness.

Decide why you are converting

• Editors need individual block controls.
• Patterns will replace repeated legacy layouts.
• Classic markup breaks under the current theme.
• Accessibility repair requires clearer structure.
• Shortcodes need documented replacement.
• Future editing depends on native blocks.
• Legacy plugins are being retired.

“Everything should be blocks” is not a sufficient business case. Conversion changes stored content and creates review work.

Know when not to convert yet

Leave stable low-change content alone when conversion provides little value. The Classic block can continue rendering valid legacy content.

Delay conversion when required shortcodes, embeds, or custom HTML lack tested replacements. Preserve public output while planning dependencies.

Do not convert during an unrelated emergency. Recovery and migration require different attention. Stabilise the site first.

Create a complete recovery point

Back up the database, uploads, themes, plugins, and configuration. Verify restoration on staging where practical.

Revisions help with individual posts. They do not preserve missing files, retired plugins, or configuration outside the content record.

Record the source post ID, URL, status, modified date, and responsible editor. Capture a frontend screenshot for visual comparison.

Use staging that matches production

Match WordPress, theme, plugins, content types, and relevant settings. Conversion results depend on available parsers and registered blocks.

Protect staging from public indexing. Remove or secure personal data. Disable production emails, payments, and external automation.

Test with the editor role that will perform production work. Administrator access can hide permission and toolbar differences.

Inventory legacy content shapes

• Plain paragraphs and headings.
• Nested ordered and unordered lists.
• Images, captions, and galleries.
• Tables.
• Blockquotes and preformatted text.
• Shortcodes.
• Embeds and iframes.
• Inline styles and custom classes.
• Scripts or forms.
• Broken or malformed HTML.

Choose one representative post from each shape. Do not test only a clean recent article. Old edge cases define migration cost.

Open legacy content in the block editor

Existing Classic Editor content may appear inside one Classic block. Inspect its frontend before editing. Save no changes yet.

Open List View and confirm the wrapper. Check the post settings, template, featured image, taxonomy, excerpt, and SEO fields separately.

The content canvas does not contain every post property. Conversion acts on content, not the entire publishing record.

Use Convert to blocks

1. Save or record the current revision.
2. Select the Classic block.
3. Open its block toolbar.
4. Choose Convert to blocks.
5. Wait for parsing to finish.
6. Open List View.
7. Inspect the new block tree.
8. Do not update yet.

The official Classic block guide documents this conversion action. It converts the selected Classic block’s content into blocks.

Understand what the parser does

WordPress reads legacy HTML and creates block representations where it recognises suitable structures. Simple semantic HTML converts most predictably.

The block data format guide explains serialization. WordPress saves block identity through comment delimiters around HTML.

The parser cannot infer every historical intention. A styled div may remain Custom HTML. A shortcode may remain unchanged text.

Conversion success means editable blocks appeared. It does not prove semantic, visual, or functional parity.

Inspect the resulting hierarchy

Open List View. Compare the new blocks with source sections. Find unexpected Groups, missing paragraphs, split lists, and flattened structures.

Check whether consecutive elements became sensible siblings. Confirm nested lists and quotations retained their intended relationships.

Do not group everything automatically. Containers need layout, style, semantic, locking, or ownership purpose.

Repair heading structure

Open Document Overview and read the Outline. Legacy content often uses heading levels for visual size rather than hierarchy.

Confirm the theme owns the primary H1 where applicable. Repair skipped levels. Convert large bold paragraphs only when they introduce sections.

Use block styles or typography presets for appearance. Heading levels should communicate the article’s structure after conversion.

Repair lists and indentation

Check ordered and unordered list types. Confirm nesting, starting numbers, reversed order, and list-item boundaries.

Legacy line breaks sometimes mimic lists without semantic markup. Rebuild those lines as List and List Item blocks.

Preview long items and nested levels on narrow screens. Excessive indentation can make mobile content unreadable. There is a whole post on whether you can trust mobile preview.

Repair images and captions

Confirm every image uses a local Media Library file. Check resolution, alignment, size, caption, link, and alternative text.

Legacy image classes can preserve outdated floats or fixed dimensions. Replace them with supported block settings where practical.

Do not rewrite alternative text from filenames automatically. Describe meaningful content in its current context. Leave decorative alternatives empty.

Repair galleries

Legacy gallery shortcodes or markup may convert differently from modern Gallery blocks. Compare image order, columns, captions, links, and crop behaviour.

Check each Gallery child in List View. Confirm every file exists. Test keyboard navigation and enlarged-image behaviour where provided.

Do not replace a working gallery merely for visual novelty. Choose the maintained implementation with the required accessibility and ownership.

Handle tables deliberately

Simple HTML tables may become Table blocks. Complex spans, embedded controls, or plugin tables can remain difficult.

Check header cells, captions, scope, row order, and responsive overflow. Do not preserve layout tables used for visual positioning.

Large data tables may need a specialist maintained block. Verify data editing, accessibility, export, and mobile requirements first.

Inventory every shortcode

Conversion does not magically replace shortcode behaviour. A Shortcode block can preserve the call while its provider remains active.

• Record the shortcode tag.
• Identify its plugin or theme owner.
• Document current output.
• Find a supported block replacement.
• Map every attribute.
• Test empty and error states.
• Plan provider retirement.

Keep the Shortcode block temporarily when replacement risk exceeds benefit. Document the dependency instead of pretending conversion removed it.

Review embeds and iframes

Recognised provider URLs may become Embed blocks. Custom iframes may remain Custom HTML. Check privacy, consent, security, and responsiveness.

Preview blocked, unavailable, and slow-provider states. Do not assume editor previews match anonymous visitor output.

Remove obsolete embeds that no longer support the page. Preserve citations or transcripts when the external media carried essential information.

Review Custom HTML blocks

Unrecognised markup can remain in Custom HTML. That may be correct. Inspect its purpose, validity, security, and maintenance owner.

Convert semantic text structures into native blocks where benefits are clear. Keep specialised markup when native blocks cannot represent it safely.

Remove inline scripts unless explicitly approved. Use maintained plugins or theme code for reusable behaviour. Content should not hide application logic.

Remove obsolete inline formatting

Legacy spans can carry font families, sizes, colours, backgrounds, and line heights. Some formatting may survive inside rich text.

Use Clear unknown formatting when WordPress offers it. Then apply approved semantic formatting and design-system presets. We wrote that up in how to remove messy formatting from WordPress blocks.

Do not remove meaningful emphasis, language direction, code, superscripts, or abbreviations blindly. Cleanup must preserve content meaning.

Preserve anchors and inbound links

Legacy headings or containers may have HTML IDs. Conversion can move, preserve, or lose them depending on the markup.

Inventory published anchors before conversion. Check navigation, table-of-contents links, campaign URLs, and external backlinks where evidence exists.

Restore stable anchors through block Advanced settings. Avoid duplicates. Add redirects when public fragment or page URLs change.

Check block validity before saving

Look for unsupported or invalid block notices. Preserve the source revision. Diagnose one representative failure before attempting recovery.

Attempt Block Recovery only after understanding likely markup differences. Compare the result with source content and frontend output.

Converting to HTML can preserve visible markup but removes structured editing. Use it as a deliberate fallback, not automatic cleanup.

Compare source and converted output

• Text and factual claims.
• Heading hierarchy.
• Lists and quotations.
• Images, captions, and links.
• Tables and galleries.
• Shortcode output.
• Forms and embeds.
• Anchors and internal navigation.
• Structured data.
• Responsive layout and reading order.

Use side-by-side previews at several widths. Visual sameness is not enough. Test keyboard operation and meaningful markup.

Save one converted post as a checkpoint

After staging review, save the converted post. Reopen it. Confirm block validity and frontend output after serialization.

Check its revision history. Restore the pre-conversion version on staging once. A tested rollback creates useful confidence.

Document time spent and manual corrections. That evidence estimates broader migration effort better than post count alone.

Scale by content shape, not random batches

Group posts sharing markup, providers, age, or template. Convert one shape at a time. Update the checklist from observed failures.

Start with low-risk content. Leave commerce, legal, complex tables, and heavily scripted pages until workflows prove reliable.

Set a batch size matching review capacity. Unreviewed converted posts are not progress. They are a larger uncertainty queue.

Treat bulk conversion as development

Automation can convert many records quickly. It can also repeat one parser mistake across the entire archive.

Use source control for scripts, database backups, dry runs, logs, and idempotent rules. Preserve original post content and IDs.

Sample every content shape after automation. Compare counts, errors, source URLs, block names, and frontend responses.

Do not install a bulk converter without testing its current compatibility and scope. Plugin automation becomes part of the migration risk.

Measure the migration before scaling it

Record preparation, conversion, repair, review, and approval time separately. One total hides the expensive content shapes.

Count shortcode failures, missing media, invalid blocks, and visual differences. These numbers support an honest archive estimate.

Include editorial review in that estimate. Parser speed rarely determines the complete migration cost.

Protect search performance during conversion

Keep the original permalink unless the information architecture also changes. Test every affected URL after saving.

Preserve meaningful headings, link destinations, image alternatives, captions, and structured content. Compare rendered text before deployment.

Check canonical settings, indexing controls, schema, and social fields. Those properties may live outside converted content.

Conversion alone should not change the publication date. Record a modified date only when policy requires it.

Plan rollback for each production edit

Define the rollback owner before production work begins. Keep the source revision and current database backup available.

Pause when output differs unexpectedly. Repeated saving can replace useful revisions and complicate investigation.

Restore one affected post when possible. Site-wide restoration can discard unrelated orders, comments, or editorial work.

Preserve editorial evidence

Record decisions for content that remains Custom HTML or shortcode based. Future editors need the reason.

Attach before and after screenshots to the migration record. Include links to relevant tests and replacement code.

Name the reviewer and approval date. Undocumented exceptions become mysterious dependencies during later maintenance.

Keep a list of deliberately unconverted posts. Revisit that list when themes, plugins, or requirements change.

Good migration records reduce repeated investigation. They also prevent neatness projects from replacing working content unnecessarily.

Create a conversion checklist

1. Define the conversion reason.
2. Back up the complete site.
3. Build matching staging.
4. Inventory legacy content shapes.
5. Convert one representative Classic block.
6. Inspect block hierarchy.
7. Repair semantics and formatting.
8. Map shortcodes and custom HTML.
9. Preserve anchors and settings.
10. Compare responsive frontend output.
11. Test save, reload, and rollback.
12. Scale only with reviewed evidence.

Assign a final approver who did not perform the conversion. Fresh review often finds missing links and altered emphasis.

Close the migration record only after production verification. A successful staging save is supporting evidence, not completion.

Frequently asked questions

The verdict

Replace legacy shortcodes only when maintained blocks meet the same content need. Test free plugins first. Then compare the $299 lifetime suite when several Pro blocks fit the migration.