WordPress FSE Child Theme Template Loading Issues

A common challenge when working with Full Site Editing (FSE) themes and child themes in WordPress: your child theme isn’t loading custom templates, instead only showing the homepage. This typically happens because the way FSE themes handle templates is fundamentally different from classic themes.

Let’s break down why this occurs and how to fix it.

Understanding FSE Template Resolution

In traditional WordPress themes, template hierarchy is primarily driven by PHP files (e.g., single.php, archive.php, page.php). FSE themes, however, rely heavily on HTML templates stored within specific directories and managed by the theme.json file.

Here’s how FSE template resolution works:

1. theme.json: This file is the cornerstone of an FSE theme. It defines styles, settings, and crucially, registers template parts and patterns. While it doesn’t directly list every single template, it influences how templates are rendered.
2. /templates Directory: This directory in your FSE theme’s root is where the main HTML templates reside (e.g., index.html, single.html, page.html, archive.html, 404.html). These are the equivalent of your PHP template files in classic themes.
3. /parts Directory: This directory contains reusable HTML template parts (e.g., header.html, footer.html, sidebar.html). These are included within your main templates using block syntax like <!-- wp:template-part {"slug":"header","tagName":"header"} /-->.
4. Site Editor: The WordPress Site Editor (under Appearance > Editor) allows users to create, modify, and assign templates directly within the WordPress admin. These user-created templates are stored in the database, overriding any theme files with the same name.

Why Child Themes Struggle with FSE Templates

The issue you’re facing with your child theme likely stems from one or more of these reasons:

1. Incorrect File Paths/Structure: FSE themes expect templates to be in the exact /templates and /parts subdirectories. If your child theme places them elsewhere, WordPress won’t find them.
2. Missing or Incorrect theme.json in Child Theme: While a child theme doesn’t always need a theme.json to inherit styles, if you intend to override or add specific FSE functionalities or templates, a theme.json might be necessary in the child theme to properly register new elements or modify existing ones.
3. Database Overrides: If you or a previous user has saved a template with the same name via the Site Editor, the database version will take precedence over your child theme’s file.
4. Caching: Server-side caching, WordPress object caching, or browser caching can sometimes prevent new template files from being recognized immediately.
5. Template Naming Conventions: Ensure your template files follow the standard FSE naming conventions (e.g., single.html, page.html, archive.html).

Solutions and Debugging Steps

Here’s a step-by-step guide to diagnose and resolve your child theme template loading issue:

1. Verify Child Theme Structure

Ensure your child theme is correctly set up as an FSE child theme.

• style.css:

/*
 Theme Name: My FSE Child Theme
 Theme URI: https://example.com/
 Description: My FSE Child Theme based on Twenty Twenty-Four.
 Author: Your Name
 Author URI: https://example.com/
 Template: twentytwentyfour
 Version: 1.0.0
 Text Domain: my-fse-child-theme
*/

• Key: The Template: header MUST match the parent theme’s directory name (e.g., twentytwentyfour).
• functions.php (Optional but Recommended for Enqueuing): While FSE themes handle styles differently, you might still need functions.php for custom PHP logic or to enqueue scripts/styles that aren’t managed by theme.json.

<?php
// No need to enqueue parent theme styles in FSE as theme.json handles it.
// Add any custom functions here.
?>

2. Correct Template File Locations

This is the most critical step for FSE child themes.

• To override a parent theme template: Copy the *.html file from the parent theme’s /templates directory to your child theme’s /templates directory, maintaining the exact same filename.
  • Example: To override single.html from twentytwentyfour, copy wp-content/themes/twentytwentyfour/templates/single.html to wp-content/themes/my-fse-child-theme/templates/single.html.
• To create a new custom template: Place your new *.html template file directly in your child theme’s /templates directory.
  • Example: For a custom “About Us” page template, create wp-content/themes/my-fse-child-theme/templates/page-about.html.
    • Important: You’ll need to assign this template to a page in the WordPress editor.
• For template parts: Similarly, place any custom or overridden template parts in your child theme’s /parts directory.
  • Example: To override header.html, copy wp-content/themes/twentytwentyfour/parts/header.html to wp-content/themes/my-fse-child-theme/parts/header.html.

3. Check for Database Overrides

User-saved templates in the Site Editor take precedence.

1. Navigate to Appearance > Editor in your WordPress admin.
2. Click on Templates or Template Parts in the left sidebar.
3. Look for any templates or template parts with the same name as the files you’re trying to load from your child theme.
4. If you find one, it will likely be marked as “Custom” or “Modified.” You have two options:
   • Delete it: If you want your child theme’s file to be used, delete the database version. WordPress will then fall back to the theme file.
   • Edit it: Edit the database version directly if you prefer to manage it through the Site Editor.

4. Clear Caches

Caching can be a major culprit.

• WordPress Caching Plugins: If you use plugins like WP Super Cache, LiteSpeed Cache, W3 Total Cache, etc., clear all their caches.
• Server-Side Caching: If your host provides server-level caching (e.g., Varnish, LiteSpeed), clear that cache as well.
• Browser Cache: Perform a hard refresh in your browser (Ctrl+F5 or Cmd+Shift+R) or clear your browser’s cache.

5. Debugging Custom Templates (e.g., page-about.html)

If you’ve created a new custom template like page-about.html:

1. Create a Page: In WordPress, go to Pages > Add New.
2. Assign the Template: In the Page Editor, open the “Page Attributes” sidebar (usually on the right). Under “Template,” you should see your new custom template listed (e.g., “About”). Select it.
3. Publish/Update: Save the page. Now, when you view this page on the frontend, it should use your page-about.html template.

6. Inspect Your HTML Templates

Open your .html template files (both in the parent and child theme) and ensure they contain valid block markup.

• Basic FSE Template Structure:

<!-- wp:pattern {"slug":"your-theme/header"} /-->
<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
    <!-- wp:post-title {"level":1} /-->
    <!-- wp:post-content /-->
</main>
<!-- /wp:group -->
<!-- wp:pattern {"slug":"your-theme/footer"} /-->

• • Note the <!-- wp:block-name {attributes} /--> syntax.

7. Check WordPress Debug Log

Enable WordPress debugging to catch any PHP errors or warnings that might be preventing templates from loading.

Add these lines to your wp-config.php file (above the /* That's all, stop editing! Happy publishing. */ line):

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false ); // Set to true if you want errors displayed on screen
@ini_set( 'display_errors', 0 ); // Hide errors from public view

Then, check the wp-content/debug.log file for any relevant messages after trying to load the templates.

By systematically going through these steps, you should be able to identify and resolve why your child theme templates aren’t loading correctly in your WordPress FSE setup. The key is understanding the FSE’s reliance on the /templates and /parts directories and the precedence of database-saved templates.