Converting Classic Themes to Block Themes

Converting classic WordPress themes to block themes represents a significant architectural transformation, moving from PHP-templated systems to HTML-based, fully editable templates. This comprehensive guide walks through the conversion process, addressing technical challenges and strategic decisions for successful migration to modern block theme architecture.

Understanding the Fundamental Differences

Classic themes rely on PHP template files containing HTML structure interspersed with PHP functions like the_title(), the_content(), and get_header(). These templates execute server-side, generating HTML dynamically. Block themes replace this approach with HTML template files containing block markup that the Site Editor can parse and modify visually.

The philosophical shift involves moving from programmatic template generation to declarative template definition. Classic themes tell WordPress “execute this PHP to generate HTML.” Block themes tell WordPress “here’s the HTML structure, render these blocks.” This declarative approach enables visual editing but requires rethinking how templates handle dynamic content.

Classic themes often include extensive functions.php files registering custom post types, taxonomies, sidebars, and adding theme support features. Block themes minimize functions.php, moving configuration into theme.json. This centralization simplifies theme architecture while exposing settings through visual interfaces.

Planning Your Conversion Strategy

Before converting, audit your classic theme’s features and dependencies. List all templates, template parts (header, footer, sidebar), custom functions, widgets, and Customizer integrations. Identify which features block themes support natively versus requiring alternative implementations.

Consider whether full conversion serves your goals. Some classic theme features—complex custom fields displays, intricate PHP logic in templates—challenge block theme architecture. You might opt for hybrid approaches, converting public-facing templates while retaining classic templates for specialized functionality.

Plan your theme.json schema before converting templates. Define your color palette, typography scale, spacing presets, and layout widths. This design system foundation informs template conversion, ensuring converted templates reference consistent design tokens rather than hardcoded values.

Creating theme.json

Begin conversion by creating a theme.json file defining your design system. Extract colors from your classic theme’s stylesheet, converting hex values into color palette presets. Map font families, sizes, and weights into typography presets. This translation creates the design token foundation for your block theme.

Review your classic theme’s Customizer settings—many map directly to theme.json settings. Custom colors become color palette presets, font choices become typography settings, layout widths become layout configuration. This mapping preserves user customization options while moving them into the modern Global Styles interface.

Configure settings to control available editor features. If your classic theme prevented custom colors to maintain brand consistency, disable custom color support in theme.json. This ensures the block theme maintains the same design constraints while offering appropriate flexibility.

Converting Templates to HTML

Template conversion involves translating PHP templates into HTML block markup. Start with simple templates like index.php or single.php. Create corresponding index.html or single.html files in your /templates directory.

Build templates using the Site Editor rather than writing block markup manually. Create a new template in the Site Editor, add necessary blocks visually, then export the HTML. This workflow leverages the visual interface while learning block markup patterns for future manual editing.

Common PHP template tags translate to specific blocks: the_title() becomes the Post Title block, the_content() becomes Post Content block, the_post_thumbnail() becomes Post Featured Image block. Loop structures translate to Query Loop blocks with nested post blocks inside.

For example, a classic single post template containing header, title, content, and footer translates to: Template Part block (header), Post Title block, Post Featured Image block, Post Content block, and Template Part block (footer). The simplicity reveals block theme elegance—templates describe structure using blocks rather than executing PHP logic.

Converting Template Parts

Classic theme files like header.php, footer.php, and sidebar.php become template parts in /parts directory. Convert header.php to header.html, maintaining the same structural elements but replacing PHP with blocks.

A classic header typically includes site branding, navigation menu, and perhaps search. In block themes, this becomes: Group or Row block containing Site Logo block, Site Title block, Navigation block, and Search block. Style these blocks using Global Styles or block-specific styling to match your classic theme’s appearance.

Navigation menus deserve special attention. Classic themes use wp_nav_menu() for menus. Block themes use the Navigation block, which stores menu content as blocks rather than the traditional menu system. Users build navigation inline using Page List blocks for automatic page links or Custom Link blocks for manual links.

Handling Dynamic Sidebar Areas

Classic themes register widget areas using register_sidebar() and display them with dynamic_sidebar(). Block themes don’t support traditional widget areas—widgets are legacy functionality maintained for backward compatibility but not recommended for new development.

Replace sidebar widget areas with template parts containing blocks. Create a sidebar.html template part including blocks for common sidebar content: Recent Posts (Query Loop block), Categories (Categories List block), Search (Search block), Archives (Archives List block). This block-based approach provides similar functionality with visual editability.

For more flexible sidebar content, consider using block patterns instead of rigid template parts. Register sidebar-focused patterns users can insert into template part blocks, providing pattern libraries for common sidebar layouts while maintaining editing flexibility.

Migrating Custom Functionality

Classic themes often include custom functions for post meta display, related posts, custom queries, and more. Block themes handle these through blocks rather than PHP functions. Built-in blocks cover many common needs: Post Author block, Post Date block, Post Terms block, Query Loop block.

For functionality not covered by core blocks, develop custom blocks rather than using PHP functions in templates. A custom “Related Posts” block provides better editor integration than PHP functions. Custom blocks appear in the inserter, work in templates and content, and integrate with Site Editor workflows.

Some functionality remains in functions.php—custom post type registration, adding theme support features, enqueueing scripts. However, minimize functions.php, moving as much configuration as possible into theme.json. This separation keeps concerns appropriately organized.

Styling and CSS Considerations

Classic theme stylesheets often contain thousands of lines targeting specific PHP-generated HTML structures. Block themes generate different HTML, potentially breaking classic styles. Approach styling systematically: start with theme.json for design system defaults, add block-specific styles as needed, use style.css for remaining custom styling.

Many classic theme styles translate to theme.json settings. Color definitions become color palette presets, typography styles become typography presets and element styles, layout styles become layout settings. This translation reduces CSS footprint while exposing styling through visual interfaces.

Remaining CSS targets block-generated HTML. Use block class names in selectors: .wp-block-post-title, .wp-block-navigation, etc. Scope styles appropriately, avoiding overly specific selectors that might conflict with user customizations through Global Styles.

Testing and Validation

Test converted themes thoroughly across different content types and templates. Verify single posts, pages, archives, search results, and 404 pages render correctly. Test with various content—short and long posts, posts with and without featured images, different post formats if supported.

Validate Global Styles functionality. Change colors, typography, spacing through Global Styles interface, confirming changes propagate correctly throughout your site. Test style variations if you’ve created them, ensuring each variation applies properly.

Use the Theme Check plugin to identify any remaining classic theme patterns or deprecated functions. This validation catches issues before distribution, ensuring your converted theme meets WordPress.org standards if you plan to distribute it.

Migration Path for Live Sites

Converting a live site’s theme requires careful planning. Development and test thoroughly on staging environments before production deployment. Consider creating the block theme as a new theme rather than converting the existing theme in-place, allowing rollback if needed.

Communicate changes to site administrators. Block themes work fundamentally differently from classic themes—educate users about the Site Editor, Global Styles, and new editing workflows. Provide documentation covering common tasks in the new paradigm.

Plan for content migration. Existing content created with classic editor or widget areas needs attention. Classic widgets can be converted to blocks using WordPress’s widget block converter. Classic editor content largely works in block themes but consider encouraging migration to blocks for consistency.

Benefits Worth the Effort

Converting to block themes delivers significant benefits: visual editing for all site elements, consistent design systems through theme.json, reduced maintenance burden with less custom PHP, better performance through optimized CSS generation, and alignment with WordPress’s future direction.

Users gain unprecedented control over their sites through visual interfaces, reducing support requests and empowering self-service customization. Developers benefit from cleaner architecture, declarative templates, and powerful design system tools that simplify complex styling challenges.

While conversion requires significant effort, the investment pays dividends in maintainability, user experience, and future compatibility. As WordPress continues evolving toward full site editing, block themes represent the sustainable path forward for WordPress theme development.