Technote

Themes & plugins Intro

Series Child theme development in practice Part 1 of 8

Template hierarchy: finding the file that renders this screen

Every child theme task starts with the same question: which file is drawing this screen? There is a way to confirm it instead of guessing.

Every child theme task opens with the same question: which file is drawing this screen right now? Answer it by guessing and you will end up creating a file nobody reads, then wondering why nothing changed. WordPress settles this with a fixed rule, and the rule is something you can verify.

The hierarchy is a candidate list, not magic

WordPress parses the incoming URL and first decides what kind of screen this is: a single post, a page, a category archive, a search result. Once the kind is settled it builds a list of candidate filenames from the most specific to the most general, and stops at the first one that actually exists.

Candidate order for a single post — the search stops at the first file that exists

The bottom of every list is index.php. That is why a theme works with nothing but index.php, and why adding files is really adding exceptions that apply to a narrower slice of the site. Once that clicks, “where do I put this file” answers itself: pick a name exactly as narrow as the change you want.

The child theme lives inside the same rule. When a candidate name matches in both places, the child’s file always wins. Copy the parent’s single.php into the child and from that moment the child draws the screen, while the parent file stays untouched. That is precisely what a child theme is for.

Print the path instead of guessing

One line tells you which file was chosen. template_include fires immediately after the decision is final, so logging its value gives you the absolute path of the file this screen is really using.

<?php
add_filter( 'template_include', function ( $template ) {
    if ( current_user_can( 'manage_options' ) ) {
        error_log( '[template] ' . $template );
    }

    return $template;
}, PHP_INT_MAX );

The very late priority is deliberate. Plugins do swap templates behind you, so only the last value reflects what actually renders. The capability check is there so that if this snippet ever survives into production it does not write a log line for every visitor.

There is a lighter method too. The classes emitted by body_class() carry the screen type, so glancing at the body tag in the browser gives you hints like single, archive or category-seo. Know the type and you know the candidate list.

Three places it usually goes wrong

First, an explicitly assigned page template beats the hierarchy. If you created page-{slug}.php and it has no effect, the editor’s template selector is almost always pointing at a different file. Explicit assignment outranks name matching.

Second, is_home() and is_front_page() are not the same thing. With a blog listing as your front page they describe the same screen, but the moment you assign a static page to the front they diverge: home.php handles the post listing, front-page.php handles the front page. Confusing the two produces the classic “everything updates except the home page”.

Third, custom post types and taxonomies look for their own name firstarchive-{type}.php, single-{type}.php, taxonomy-{taxonomy}.php. Without those files the request falls through to the generic archive, so if a screen looks suspiciously like every other listing, check the filename before anything else.

Same task — the order of the first two steps decides how long it takes

Wider reading on theme structure sits in the Themes & plugins archive, and if you would rather have an existing site’s theme structure reviewed and tidied, that assessment is part of our optimization program.

Next part

With the right file identified, styling comes next — and that is where the most common child theme frustration lives: “my CSS does not apply”. The next part is about load order, and to give away the conclusion: !important is not the answer.

More on this topic

All technotes

Themes & plugins Practical

Decide the editable regions before you design them

A design the CMS cannot express stays up for negotiation long after it ships. Deciding what editors may change, first, removes the negotiation entirely.

Designers 6 min read

₩270,000 · Join the program