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
- Audit the classic theme and list every template, widget area, menu and Customizer option.
- Back up the site and spin up a local or staging copy.
- Scaffold the block theme folder:
style.css,theme.json,templates/,parts/,patterns/. - Convert
header.phpandfooter.phpintoparts/header.htmlandparts/footer.html. - Convert
index.phpintotemplates/index.html(the only mandatory template). - Convert
single.php,page.php,archive.php,search.php,404.php. - Move colors, fonts, spacing and layout widths from
functions.phpand CSS intotheme.json. - Rebuild repeated markup (hero, CTA, cards, footer columns) as block patterns.
- Keep genuine logic (CPTs, hooks, shortcodes, integrations) in a slimmed-down
functions.phpor move it into a plugin. - Test on staging with real content, then switch live and keep the old theme as rollback.

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.jsonplus 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
- Full backup (files + database) with a tool such as Duplicator, WPvivid or All-in-One WP Migration.
- Create a local environment (wp-env, Studio, Local, DevKinsta) or a staging subdomain.
- 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.
- Keep the classic theme installed. You will need it for visual comparison and rollback.

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.phpand inserted with the Shortcode block. - Register the parts in
theme.jsonso they appear with the right area icon in the Site Editor:
"templateParts": [
{ "name": "header", "title": "Header", "area": "header" },
{ "name": "footer", "title": "Footer", "area": "footer" }
]

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
!importantrules and long selector chains will fight the Site Editor. Clean them as you go.

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: nofor patterns used only inside templates.Block Types: core/template-part/headerto 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_varsfilter instead ofpre_get_postshacks. - 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.
- 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.
- Theme Unit Test Data: long titles, no featured image, nested comments, password-protected posts, very long tables, wide and full alignments.
- Editor sanity: open Appearance > Editor and confirm every template part shows and is editable without errors in the browser console.
- Theme Check plugin if you plan to distribute the theme.
- Accessibility: keyboard navigation of the Navigation block overlay, visible focus styles, correct heading order, color contrast of your theme.json palette.
- 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. - 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).
- Forms, carts, logins: test every transactional flow, especially WooCommerce and membership pages.
- 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.

Step 12: go live and keep a rollback path
- Take a fresh backup of production.
- Activate the block theme during a low-traffic window.
- Re-assign menus inside the Navigation block if they did not import automatically.
- Rebuild any widget content that did not map to a template part.
- Paste back Customizer Additional CSS into Global Styles > Additional CSS if still needed.
- Crawl the site with Screaming Frog or a similar tool and compare status codes, titles and H1s against the pre-migration crawl.
- 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-contentbecomes.wp-block-post-content,.site-headerbecomes 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.
