Under the Hood: `wp_template` vs. `wp_template_part`

When you edit a template in the Site Editor, WordPress doesn't edit your HTML files. Instead, it saves a copy of the block markup into the database. To manage this, WordPress introduced two new internal Post Types.

Understanding these post types is crucial for debugging why a template isn't updating or why "Clear Customizations" is appearing.

1. The Two Post Types

Both live in the wp_posts table, just like standard Pages or Posts.

`wp_template`

Corresponds to: Files in the templates/ directory (e.g., index.html, single.html, 404.html).
Purpose: Represents a full-page layout.
Slug Structure: usually theme-slug//template-name (e.g., twentytwentyfour//single).

`wp_template_part`

Corresponds to: Files in the parts/ directory (e.g., header.html, footer.html).
Purpose: Represents a reusable section included inside a template.
Slug Structure: theme-slug//part-name (e.g., twentytwentyfour//header).

2. The Resolution Hierarchy (Shadowing)

WordPress uses a specific logic to decide what to show the user. It checks the database first, then the filesystem.

Database Check: Does a wp_template post exist with the slug my-theme//single and post_status = 'publish'?
- Yes: Render the content from post_content in the database. (Ignore the file).
- No: Look for templates/single.html in the active theme folder.

Key Takeaway: The moment you click "Save" in the Site Editor, you create a database entry that "shadows" (hides) your physical HTML file.

3. Inspecting the Database

If you are comfortable with SQL or tools like PHPMyAdmin, you can see exactly what customizations are active.

Query to see all customized templates:

SELECT ID, post_name, post_status 
FROM wp_posts 
WHERE post_type = 'wp_template';

Query to see all customized parts:

SELECT ID, post_name, post_status 
FROM wp_posts 
WHERE post_type = 'wp_template_part';

4. "Clearing" Customizations

When you click "Clear Customizations" in the Site Editor, WordPress effectively runs:

DELETE FROM wp_posts WHERE ID = [The ID of the shadow template];

Once the row is deleted, the hierarchy logic (Step 2 above) fails the Database Check and falls back to reading your .html file again.

5. Why the Slug Includes the Theme Name?

You might notice slugs like twentytwentyfour//index.

WordPress namespaces templates to the active theme. This allows you to switch themes without losing your customizations.

If you customize the Header in Theme A, it saves as theme-a//header.
If you switch to Theme B, WordPress looks for theme-b//header.
It does not load the customizations from Theme A, preventing layout breakage.

Created: March 19, 2026 • Last Modified: March 19, 2026

Docs Login

Under the Hood: wp_template vs. wp_template_part