ahel
Start free

Classic Template Hierarchy

SkillSearch

Choose, create, or audit classic PHP WordPress template files for WP 7.1 using the template hierarchy. Covers `template-loader.php`, `index.php` fallback, `front-page.php` vs `home.php`, page/single/archive/taxonomy/search/404/attachment templates, `get_template_part()` with `$args`, child-theme override order, `template_include`, the `is_sitemap()` conditional, and why `template_redirect` should not include-and-exit. Use when deciding which classic template file to add or reviewing page.php/404.php/single/archive behavior.

Available today. Use it from your connected AI after setup.

Connect ahel once, and every AI you use reads what you have installed.

Then ask your AI: use the Classic Template Hierarchy skill

What this skill tells your AI

The instructions your AI receives, as published by lonsdale201/wp-agent-skills in theme-development/classic-template-hierarchy/SKILL.md and read by ahel’s review.

Use this when deciding which PHP template file a classic theme should contain, or when auditing why WordPress loads the wrong template.

This is a classic PHP theme skill. Do not apply FSE/block-template assumptions such as templates/page.html.

When to Use This Skill

  • Adding page.php, single.php, archive.php, 404.php, or similar template files.
  • Debugging front page vs blog index behavior.
  • Converting static pages into WordPress templates.
  • Creating custom page templates.
  • Reviewing template_include, template_redirect, get_template_part, or child-theme override behavior.

Loader Model in WP 7.1

wp-includes/template-loader.php checks query conditionals, asks a get_*_template() function for candidates, then falls back to index.php.

Important WP 7.1 details:

  • The final path passes through template_include.
  • WordPress resolves the returned template through realpath().
  • The final included template must be a readable .php or .html file.
  • wp_before_include_template fires immediately before inclusion.

Do not include a template and call exit from template_redirect. Core's own docblock says template loading should be changed via template_include so later hooks still run.

WordPress 7.1 adds WP_Query::$is_sitemap, WP_Query::is_sitemap(), and the global is_sitemap() conditional for requests with the sitemap query var. Like other conditional tags, call it only after the main query is parsed. It does not add a sitemap.php theme hierarchy entry. Core or an SEO plugin normally handles sitemap output during routing/hooks; do not render an XML sitemap through an HTML theme template merely because the conditional exists.

Child Theme Lookup

locate_template() searches:

  1. Active stylesheet directory, usually child theme.
  2. Parent template directory, when a child theme is active.
  3. wp-includes/theme-compat/ fallback for a few legacy files.

This means a child theme can override a parent template by adding the same relative file path.

Main Template Files

RequestPreferred classic files
Site front pagefront-page.php, then the matching page/home flow, then index.php
Blog posts indexhome.php, then index.php
Static pagecustom page template, page-{slug}.php, page-{id}.php, page.php, singular.php, index.php
Single post/CPTcustom post template, single-{post_type}-{slug}.php, single-{post_type}.php, single.php, singular.php, index.php
CPT archivearchive-{post_type}.php, archive.php, index.php
Generic archivearchive.php, index.php
Categorycategory-{slug}.php, category-{id}.php, category.php, archive.php, index.php
Tagtag-{slug}.php, tag-{id}.php, tag.php, archive.php, index.php
Custom taxonomytaxonomy-{taxonomy}-{term}.php, taxonomy-{taxonomy}-{term_id}.php, taxonomy-{taxonomy}.php, taxonomy.php, archive.php, index.php
Authorauthor-{nicename}.php, author-{id}.php, author.php, archive.php, index.php
Datedate.php, archive.php, index.php
Searchsearch.php, index.php
404404.php, index.php
Attachment{mime_type}-{sub_type}.php, {sub_type}.php, {mime_type}.php, attachment.php, singular.php, index.php

front-page.php is special: it wins for the site front page whether the front page is a static page or the posts index.

home.php is the blog posts index, not the homepage in every configuration.

Template Responsibilities

FileResponsibility
index.phpFinal fallback. Should render a valid loop and no-results state.
header.phpDoctype, <html>, <head>, wp_head(), opening <body>, wp_body_open(), site header.
footer.phpSite footer, wp_footer(), closing body/html.
front-page.phpBespoke front page layout.
home.phpBlog posts index.
page.phpStatic WordPress pages. Not posts, not archives.
single.phpSingle posts and CPTs when no more specific single template exists.
singular.phpShared fallback for pages/posts/attachments before index.php.
archive.phpShared fallback for taxonomy/date/author/post type archives.
search.phpSearch results page.
404.phpNot-found response view; include search/navigation help.
comments.phpComment list/form markup loaded by comments_template().
searchform.phpCustom search form loaded by get_search_form().

Thin Template Pattern

Keep top-level templates small. Let template parts carry repeated post markup.

<?php
/**
 * Main fallback template.
 *
 * @package MyTheme
 */

get_header();
?>

<main id="primary" class="site-main">
    <?php if ( have_posts() ) : ?>
        <?php
        while ( have_posts() ) :
            the_post();

            get_template_part(
                'template-parts/content',
                get_post_type(),
                array(
                    'show_excerpt' => is_archive() || is_search(),
                )
            );
        endwhile;

        the_posts_pagination();
        ?>
    <?php else : ?>
        <?php get_template_part( 'template-parts/content', 'none' ); ?>
    <?php endif; ?>
</main>

<?php
get_footer();

get_template_part( $slug, $name, $args ) searches {$slug}-{$name}.php, then {$slug}.php, and passes $args into the template. Use this instead of setting temporary globals for template parts.

Custom Page Templates

WordPress scans PHP files in the theme root and one directory deep for Template Name. In WordPress 7.1, WP_Theme::get_post_templates() parses Template Name and Template Post Type through get_file_data(). Keep both headers within the first 8 KB of the file and use normal header-comment syntax; do not generate them dynamically or place a large preamble before them.

<?php
/**
 * Template Name: Landing Page
 * Template Post Type: page
 *
 * @package MyTheme
 */

get_header();

while ( have_posts() ) :
    the_post();
    get_template_part( 'template-parts/content', 'landing' );
endwhile;

get_footer();

Put these in page-templates/ when there are several. Do not create page-about.php for editor-selectable layouts; use a custom page template header.

Safe Template Overrides

To override the selected template globally or conditionally:

add_filter( 'template_include', 'mytheme_template_include' );

function mytheme_template_include( string $template ): string {
    if ( ! is_singular( 'event' ) ) {
        return $template;
    }

    $event_template = locate_template( array( 'single-event.php' ) );

    return $event_template ?: $template;
}

Never build a template path directly from $_GET, $_POST, route segments, or unvalidated meta. Use fixed candidate lists and locate_template().

Required Header/Footer Hooks

header.php:

<!doctype html>
<html <?php language_attributes(); ?>>
<head>
    <meta charset="<?php bloginfo( 'charset' ); ?>">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <?php wp_head(); ?>
</head>
<body <?php body_class(); ?>>
<?php wp_body_open(); ?>

footer.php:

<?php wp_footer(); ?>
</body>
</html>

Missing wp_head() or wp_footer() breaks core, plugins, admin bar assets, and enqueued scripts/styles.

Common Mistakes

  • Treating home.php as the marketing homepage. It is the blog posts index.
  • Putting all routes into page.php; posts, archives, search, and 404 use other hierarchy branches.
  • Creating one-off page-{slug}.php files when the editor needs a reusable page template.
  • Directly include-ing template files instead of using get_header(), get_footer(), comments_template(), or get_template_part().
  • Using template_redirect to include a file and exit.
  • Returning request-controlled paths from template_include.
  • Forgetting that child theme files override parent files by relative path.
  • Inventing a sitemap.php theme template because WordPress 7.1 added is_sitemap(); no such hierarchy branch exists.

Cross-References

  • Theme bootstrapping, folders, assets: classic-theme-structure
  • Broader WP security review: wp-security-audit

References

Signals

GitHub stars
22
Forks
2
Last commit
Sep 2026
Advanced
Catalog kind
skill
Gateway key
classic-template-hierarchy
Source
github.com/lonsdale201/wp-agent-skills

github.com/lonsdale201/wp-agent-skills

More in Search

azure-ai
Skill · microsoftflags
Skill · verceldashboard
Skill · nexu-ioexa-search
Skill · affaan-madding-mcp-store-servers
Skill · posthoglark-im
Skill · larksuite