How to Convert a Classic WordPress Theme to a Block Theme: A File-by-File Migration Walkthrough

If you still run a PHP-based theme and want Full Site Editing, the real question is not why but in which order. This guide shows you how to convert a classic theme to a block theme file by file: every classic template gets a block template equivalent, every functions.php design setting gets a home in theme.json, and every risky part gets a decision point (keep as PHP, or rebuild as a block pattern).

No theory dump. This is the exact conversion sequence we use at MarkupDude when we migrate production themes, including how to test the new theme before switching it live.

TL;DR: the 10-step conversion sequence

  1. Audit the classic theme and list every template, widget area, menu and Customizer option.
  2. Back up the site and spin up a local or staging copy.
  3. Scaffold the block theme folder: style.css, theme.json, templates/, parts/, patterns/.
  4. Convert header.php and footer.php into parts/header.html and parts/footer.html.
  5. Convert index.php into templates/index.html (the only mandatory template).
  6. Convert single.php, page.php, archive.php, search.php, 404.php.
  7. Move colors, fonts, spacing and layout widths from functions.php and CSS into theme.json.
  8. Rebuild repeated markup (hero, CTA, cards, footer columns) as block patterns.
  9. Keep genuine logic (CPTs, hooks, shortcodes, integrations) in a slimmed-down functions.php or move it into a plugin.
  10. Test on staging with real content, then switch live and keep the old theme as rollback.
wordpress code editor

What actually changes between classic and block themes

Area Classic theme Block theme
Templates PHP files in theme root HTML files in /templates
Reusable areas get_header(), get_footer(), get_template_part() Template parts in /parts
Design settings Customizer + CSS + add_theme_support() theme.json + Global Styles
Menus register_nav_menus() Navigation block
Widgets register_sidebar() Template parts and patterns
Editing UI Appearance > Customize Appearance > Editor (Site Editor)
Loop while ( have_posts() ) Query Loop block

Important: your posts, pages and media stay untouched. What you can lose is theme-level configuration: widget placement, Customizer values, menu locations and any CSS tied to old class names.

Step 1: audit before you touch a single file

Open the classic theme folder and write down what you find. A simple inventory saves hours later.

  • Template files present (and which ones are actually used, check with Query Monitor).
  • Widget areas registered and which are populated on the live site.
  • Customizer options clients rely on (logo, colors, footer text, social links).
  • Hardcoded CSS selectors such as .entry-content, .site-header, .nav-primary.
  • Functions that are not design: custom post types, shortcodes, REST endpoints, WooCommerce tweaks, ACF field groups.
  • Plugins hooking into theme actions, for example do_action( 'mytheme_before_content' ).

Decision point: full block theme or hybrid?

  • Full block theme if the site is mostly editorial, marketing or brochure content. Best long-term choice.
  • Hybrid theme if you have heavy PHP logic, a membership system or a large WooCommerce build. You keep PHP templates and add theme.json plus a few block template parts, then migrate progressively.

A hybrid step is a legitimate milestone, not a failure. Many agencies ship theme.json first, then convert templates one by one over several sprints.

Step 2: back up and build on a copy

  1. Full backup (files + database) with a tool such as Duplicator, WPvivid or All-in-One WP Migration.
  2. Create a local environment (wp-env, Studio, Local, DevKinsta) or a staging subdomain.
  3. Import the real content, or at least the Theme Unit Test Data from the WordPress Themes Team repository so you have long titles, nested comments, galleries and sticky posts.
  4. Keep the classic theme installed. You will need it for visual comparison and rollback.
wordpress code editor

Step 3: scaffold the block theme folder

A valid block theme needs surprisingly little. Minimum viable structure:

my-block-theme/
  style.css          (theme header + remaining custom CSS)
  theme.json         (design tokens and layout)
  templates/
    index.html       (required)
  parts/
    header.html
    footer.html
  patterns/
  functions.php      (optional)
  screenshot.png

Your style.css still needs the standard theme header. If you are converting an existing public theme, bump the version and change the folder name so you can install both themes side by side.

/*
Theme Name: My Block Theme
Author: MarkupDude
Version: 1.0.0
Requires at least: 6.5
Tested up to: 6.9
Text Domain: my-block-theme
*/

Shortcut worth knowing

The official Create Block Theme plugin can export the current Site Editor state into real theme files, create a blank block theme, and even export fonts into the theme folder. It does not magically convert PHP to HTML, but it removes a lot of manual file writing once your templates look right in the editor.

Step 4: header.php becomes parts/header.html

In a classic theme, header.php usually holds the doctype, wp_head(), the opening body tag, the logo and the main menu. In a block theme, WordPress handles the document shell for you. Delete all of it. You only keep the visible header markup.

Classic:

<header class="site-header">
  <div class="container">
    <?php the_custom_logo(); ?>
    <?php wp_nav_menu( array( 'theme_location' => 'primary' ) ); ?>
  </div>
</header>

Block equivalent in parts/header.html:

<!-- wp:group {"tagName":"header","layout":{"type":"constrained"}} -->
<header class="wp-block-group">
  <!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} -->
  <div class="wp-block-group">
    <!-- wp:site-logo {"width":160} /-->
    <!-- wp:navigation {"overlayMenu":"mobile"} /-->
  </div>
  <!-- /wp:group -->
</header>
<!-- /wp:group -->

What to drop, what to keep

  • Drop: doctype, <html>, <head>, wp_head(), body_class(), skip links (the editor can output one), sticky-header JS if CSS can do it.
  • Keep as PHP: nothing, ideally. If you have a dynamic announcement bar driven by ACF, build it as a custom dynamic block or a shortcode placed in the header part.
  • Pro tip: do not hand-write this HTML. Build the header visually in Appearance > Editor, then copy the block markup from the code editor view (three-dot menu > Code editor) into your file.

Step 5: footer.php becomes parts/footer.html

Same logic: remove wp_footer() and the closing tags, keep the visible columns.

  • Footer widget areas become columns blocks containing navigation, latest posts or paragraph blocks.
  • A dynamic copyright year is the classic sticking point. Options: a Site Title block + static year, a small custom dynamic block, or a shortcode registered in functions.php and inserted with the Shortcode block.
  • Register the parts in theme.json so they appear with the right area icon in the Site Editor:
"templateParts": [
  { "name": "header", "title": "Header", "area": "header" },
  { "name": "footer", "title": "Footer", "area": "footer" }
]
wordpress code editor

Step 6: index.php becomes templates/index.html

templates/index.html is the only required template. It is your fallback for everything, so get it right before building the rest.

Classic loop:

<?php get_header(); ?>
<?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
  <h2><?php the_title(); ?></h2>
  <?php the_excerpt(); ?>
<?php endwhile; endif; ?>
<?php get_footer(); ?>

Block equivalent:

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
  <!-- wp:query {"queryId":1,"query":{"perPage":10,"postType":"post","inherit":true}} -->
  <div class="wp-block-query">
    <!-- wp:post-template -->
      <!-- wp:post-featured-image {"isLink":true} /-->
      <!-- wp:post-title {"isLink":true,"level":2} /-->
      <!-- wp:post-excerpt /-->
    <!-- /wp:post-template -->
    <!-- wp:query-pagination -->
      <!-- wp:query-pagination-previous /-->
      <!-- wp:query-pagination-numbers /-->
      <!-- wp:query-pagination-next /-->
    <!-- /wp:query-pagination -->
    <!-- wp:query-no-results -->
      <!-- wp:paragraph --><p>Nothing found.</p><!-- /wp:paragraph -->
    <!-- /wp:query-no-results -->
  </div>
  <!-- /wp:query -->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

Note "inherit":true. That is the block equivalent of the main query and it is what makes archives, search and pagination behave correctly.

Step 7: convert the remaining templates

Work in order of traffic: single, page, archive, search, 404. Use this mapping table as your checklist.

Classic file Block theme file Key blocks to use
header.php parts/header.html Site Logo, Site Title, Navigation
footer.php parts/footer.html Columns, Navigation, Paragraph
sidebar.php parts/sidebar.html Latest Posts, Categories, Search
index.php templates/index.html Query Loop, Post Template
front-page.php templates/front-page.html Patterns, Cover, Columns
home.php templates/home.html Query Loop
single.php templates/single.html Post Title, Post Content, Post Date, Post Terms, Comments
single-{cpt}.php templates/single-{cpt}.html Post Content + custom blocks
page.php templates/page.html Post Title, Post Content
archive.php templates/archive.html Query Title, Term Description, Query Loop
category.php / tag.php templates/category.html / tag.html Query Title, Query Loop
taxonomy-{tax}.php templates/taxonomy-{tax}.html Query Title, Query Loop
author.php templates/author.html Query Title, Post Author Biography
search.php templates/search.html Query Title (search), Search block, Query Loop
404.php templates/404.html Heading, Search, Latest Posts
comments.php Comments block inside single.html Comments, Comment Template, Post Comments Form
searchform.php No file needed Search block
Page templates (Template Name) templates/page-{slug}.html or custom template in theme.json Any

Custom page templates

Classic page templates declared with a Template Name: comment are replaced by entries in theme.json:

"customTemplates": [
  {
    "name": "page-full-width",
    "title": "Full Width",
    "postTypes": [ "page" ]
  }
]

Then create templates/page-full-width.html. Editors will see Full Width in the Template dropdown exactly as before.

Step 8: move functions.php design code into theme.json

This is where most of the convert classic theme to block theme work pays off. Block themes automatically enable several theme supports, so a lot of old code can simply be deleted.

Classic code New home
add_theme_support( 'title-tag' ) Delete (automatic)
add_theme_support( 'post-thumbnails' ) Delete (automatic in block themes)
add_theme_support( 'html5', ... ) Delete (automatic)
add_theme_support( 'responsive-embeds' ) Delete (automatic)
add_editor_style() Delete, style.css loads in the editor automatically
editor-color-palette settings.color.palette
editor-font-sizes settings.typography.fontSizes
editor-gradient-presets settings.color.gradients
$content_width / align-wide settings.layout.contentSize and wideSize
register_nav_menus() Navigation block (menus become wp_navigation entries)
register_sidebar() Template parts and patterns
Customizer CSS output styles in theme.json or Global Styles
Font enqueues (Google Fonts) settings.typography.fontFamilies with local font files
CPTs, taxonomies, shortcodes, hooks Keep in functions.php or move to a site plugin
wp_enqueue_style() for block-specific CSS wp_enqueue_block_style() for on-demand loading

A realistic theme.json starting point

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "appearanceTools": true,
    "layout": { "contentSize": "720px", "wideSize": "1180px" },
    "color": {
      "defaultPalette": false,
      "palette": [
        { "slug": "base", "color": "#ffffff", "name": "Base" },
        { "slug": "contrast", "color": "#111111", "name": "Contrast" },
        { "slug": "primary", "color": "#0b5fff", "name": "Primary" }
      ]
    },
    "typography": {
      "fluid": true,
      "fontSizes": [
        { "slug": "small", "size": "0.875rem", "name": "Small" },
        { "slug": "medium", "size": "1rem", "name": "Medium" },
        { "slug": "large", "size": "1.5rem", "name": "Large" }
      ]
    },
    "spacing": { "units": [ "px", "rem", "%", "vw" ] }
  },
  "styles": {
    "color": { "background": "var(--wp--preset--color--base)", "text": "var(--wp--preset--color--contrast)" },
    "typography": { "fontSize": "var(--wp--preset--font-size--medium)", "lineHeight": "1.6" },
    "elements": {
      "link": { "color": { "text": "var(--wp--preset--color--primary)" } },
      "button": { "color": { "background": "var(--wp--preset--color--primary)", "text": "var(--wp--preset--color--base)" }, "spacing": { "padding": { "top": "0.8rem", "bottom": "0.8rem", "left": "1.4rem", "right": "1.4rem" } } }
    },
    "blocks": {
      "core/post-title": { "typography": { "fontSize": "var(--wp--preset--font-size--large)" } }
    }
  },
  "templateParts": [
    { "name": "header", "title": "Header", "area": "header" },
    { "name": "footer", "title": "Footer", "area": "footer" }
  ]
}

Decision point: what stays in CSS?

You will not move 100% of your stylesheet into theme.json, and you should not try.

  • Move to theme.json: colors, font sizes, font families, spacing scale, layout widths, button and link styles, per-block defaults.
  • Keep in style.css: complex selectors, animations, media queries that presets cannot express, third-party plugin overrides, print styles.
  • Watch out for specificity: theme.json outputs CSS custom properties and low-specificity rules. Old !important rules and long selector chains will fight the Site Editor. Clean them as you go.
wordpress code editor

Step 9: rebuild repeated markup as block patterns

Anything that was a get_template_part() call or a shortcode used repeatedly by editors should become a block pattern. Patterns in the /patterns folder are auto-registered. No PHP registration needed.

patterns/cta-banner.php:

<?php
/**
 * Title: CTA Banner
 * Slug: my-block-theme/cta-banner
 * Categories: call-to-action
 * Keywords: cta, banner
 */
?>
<!-- wp:cover {"dimRatio":60,"align":"full"} -->
<div class="wp-block-cover alignfull">...</div>
<!-- /wp:cover -->

Useful flags:

  • Inserter: no for patterns used only inside templates.
  • Block Types: core/template-part/header to offer header variations when editors create a new header.
  • Patterns support translation functions, so your strings stay localizable.

Decision point: pattern, synced pattern, or custom block?

Need Best choice
Reusable layout, edited freely each time Theme pattern (unsynced)
Identical content everywhere, edited once Synced pattern (stored in DB)
Output depends on PHP logic or external data Custom dynamic block with render callback
Legacy functionality used in post content Keep the shortcode, insert via Shortcode block

Step 10: what legitimately stays in PHP

Block themes still load functions.php. Keep it, but keep it honest:

  • Custom post types and taxonomies: better in a site plugin so they survive a future theme change.
  • Custom blocks registered with register_block_type().
  • Block variations and block styles via register_block_style().
  • Query modifications using the query_loop_block_query_vars filter instead of pre_get_posts hacks.
  • Third-party integrations: WooCommerce templates, forms, analytics, security headers.
  • Pattern categories via register_block_pattern_category().

If a plugin depends on an action you fired in the old header, keep firing it. You can add do_action() calls back with a small dynamic block or with hooks like wp_body_open.

Step 11: test the block theme before switching it live

This is the step people skip, and it is the step that causes emergency rollbacks. Run through the list below on staging.

  1. Template coverage: visit a post, a page, a category, a tag, an author archive, a search result, a 404, a paginated archive, a CPT single and archive.
  2. Theme Unit Test Data: long titles, no featured image, nested comments, password-protected posts, very long tables, wide and full alignments.
  3. Editor sanity: open Appearance > Editor and confirm every template part shows and is editable without errors in the browser console.
  4. Theme Check plugin if you plan to distribute the theme.
  5. Accessibility: keyboard navigation of the Navigation block overlay, visible focus styles, correct heading order, color contrast of your theme.json palette.
  6. Performance: compare Core Web Vitals before and after. Block themes often ship less CSS, but check that fonts are preloaded and that wp_enqueue_block_style() is used for heavy block CSS.
  7. SEO parity: titles, meta descriptions, canonical tags, schema output and breadcrumbs still work (most of this comes from your SEO plugin, but breadcrumb shortcodes placed in old templates must be re-added).
  8. Forms, carts, logins: test every transactional flow, especially WooCommerce and membership pages.
  9. Redirect and internal links: URLs do not change during a theme conversion, so any 404 after the switch means a template is missing, not an SEO problem.

Testing with live visitors still on the old theme

If you cannot use staging, use a theme preview or theme switcher plugin that serves the block theme only to logged-in administrators. You can also preview templates with the ?preview_theme style tools available in some hosting dashboards. Never iterate on production with the new theme active.

wordpress code editor

Step 12: go live and keep a rollback path

  1. Take a fresh backup of production.
  2. Activate the block theme during a low-traffic window.
  3. Re-assign menus inside the Navigation block if they did not import automatically.
  4. Rebuild any widget content that did not map to a template part.
  5. Paste back Customizer Additional CSS into Global Styles > Additional CSS if still needed.
  6. Crawl the site with Screaming Frog or a similar tool and compare status codes, titles and H1s against the pre-migration crawl.
  7. Watch Search Console coverage and Core Web Vitals for two weeks.

Rollback plan: keep the classic theme installed for at least one month. Switching back is one click, and your content is untouched either way.

Common pitfalls when you convert a classic theme to a block theme

  • Forgetting index.html. Without it, WordPress does not recognize the theme as a block theme.
  • Hand-writing block markup. One missing closing comment and the template breaks silently. Build in the editor, then export.
  • Templates stuck on old markup. Once you edit a template in the Site Editor, the database version wins. Use Clear customizations to fall back to the theme file after you change it.
  • CSS written for classic class names. .entry-content becomes .wp-block-post-content, .site-header becomes a group wrapper. Audit and rename.
  • Google Fonts from a CDN. Host fonts locally in the theme and declare them in theme.json for privacy and performance.
  • Page builder content. If pages were built with Elementor, Divi or WPBakery, a block theme will not convert that content. Plan a separate content migration.
  • Translating strings. Text inside HTML templates is not translatable. Put translatable copy inside patterns (PHP) instead.

How long does a realistic migration take?

Site type Typical effort Main risk
Small blog or brochure site 1 to 3 days Lost widget content
Content site with CPTs and custom archives 1 to 2 weeks Query Loop limitations
WooCommerce or membership site 3 to 6 weeks Checkout and account templates
Legacy page-builder site Treat as a rebuild Content locked in shortcodes

FAQ

Can you switch themes in WordPress without losing content?

Yes. Posts, pages, media and custom fields live in the database and are not tied to the theme. What you can lose are theme-specific settings: widgets, menu locations, Customizer values and any content stored in theme options. Export those before switching.

Is there a plugin that converts a classic theme to a block theme automatically?

No plugin converts PHP templates into block HTML automatically. The official Create Block Theme plugin is the closest helper: it creates a blank block theme, exports your Site Editor changes into real files, and bundles fonts. The template logic still has to be rebuilt by a human.

Can I convert gradually instead of all at once?

Yes, that is the hybrid approach. Add theme.json to your classic theme first to gain Global Styles, then enable block template parts, then move templates one at a time. The site keeps working at every stage.

Do block themes still use functions.php?

Yes. Block themes load functions.php normally. It should only contain real logic such as custom blocks, block styles, CPT registration and integrations. Design values belong in theme.json.

What happens to my child theme?

Child themes work with block themes too. A child block theme can override individual template files, add its own theme.json (merged with the parent) and add patterns. If your current child theme only contains CSS overrides, most of that CSS will become theme.json values.

Will converting hurt my SEO?

Not if URLs and content stay the same. Risks come from missing templates, lost breadcrumb or schema snippets that were hardcoded in PHP templates, and heading structure changes. Crawl before and after, and compare.

Which template should I build first?

Start with index.html, then single.html and page.html. Those three cover the majority of page views on most sites and everything else falls back to index.html in the meantime.

Final checklist

  • Audit done and inventory written
  • Backup taken, staging environment live
  • style.css header, theme.json, templates/index.html in place
  • header.html and footer.html rebuilt and registered as template parts
  • single, page, archive, search and 404 templates created
  • Design tokens moved from functions.php to theme.json
  • Repeated layouts converted to patterns
  • Remaining PHP justified and documented
  • Full test pass with unit test data
  • Go-live window scheduled, rollback theme kept installed

Converting a classic theme is not a weekend rewrite of everything at once. It is a sequence: shell first, loop second, design tokens third, patterns last. Follow that order and the migration stays boring, which is exactly what you want from a theme change.

Need a second pair of eyes on your migration, or a full conversion handled for you? Talk to the team at MarkupDude and we will audit your classic theme and give you a file-by-file conversion plan.

Leave a Comment