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.

No other account needed.

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:

Active stylesheet directory, usually child theme.
Parent template directory, when a child theme is active.
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

Request	Preferred classic files
Site front page	`front-page.php`, then the matching page/home flow, then `index.php`
Blog posts index	`home.php`, then `index.php`
Static page	custom page template, `page-{slug}.php`, `page-{id}.php`, `page.php`, `singular.php`, `index.php`
Single post/CPT	custom post template, `single-{post_type}-{slug}.php`, `single-{post_type}.php`, `single.php`, `singular.php`, `index.php`
CPT archive	`archive-{post_type}.php`, `archive.php`, `index.php`
Generic archive	`archive.php`, `index.php`
Category	`category-{slug}.php`, `category-{id}.php`, `category.php`, `archive.php`, `index.php`
Tag	`tag-{slug}.php`, `tag-{id}.php`, `tag.php`, `archive.php`, `index.php`
Custom taxonomy	`taxonomy-{taxonomy}-{term}.php`, `taxonomy-{taxonomy}-{term_id}.php`, `taxonomy-{taxonomy}.php`, `taxonomy.php`, `archive.php`, `index.php`
Author	`author-{nicename}.php`, `author-{id}.php`, `author.php`, `archive.php`, `index.php`
Date	`date.php`, `archive.php`, `index.php`
Search	`search.php`, `index.php`
404	`404.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

File	Responsibility
`index.php`	Final fallback. Should render a valid loop and no-results state.
`header.php`	Doctype, `<html>`, `<head>`, `wp_head()`, opening `<body>`, `wp_body_open()`, site header.
`footer.php`	Site footer, `wp_footer()`, closing body/html.
`front-page.php`	Bespoke front page layout.
`home.php`	Blog posts index.
`page.php`	Static WordPress pages. Not posts, not archives.
`single.php`	Single posts and CPTs when no more specific single template exists.
`singular.php`	Shared fallback for pages/posts/attachments before `index.php`.
`archive.php`	Shared fallback for taxonomy/date/author/post type archives.
`search.php`	Search results page.
`404.php`	Not-found response view; include search/navigation help.
`comments.php`	Comment list/form markup loaded by `comments_template()`.
`searchform.php`	Custom 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
Escaping, nonces, safe template output: classic-theme-security-standards
Broader WP security review: wp-security-audit

References

Official documentation: https://developer.wordpress.org/themes/classic-themes/basics/template-hierarchy/
Official documentation: https://developer.wordpress.org/themes/classic-themes/basics/template-files/
Official documentation: https://developer.wordpress.org/themes/classic-themes/templates/page-template-files/
Verified source paths:
- wp-includes/template-loader.php
- wp-includes/template.php
- wp-includes/general-template.php
- wp-includes/class-wp-theme.php
- wp-content/themes/storefront/index.php
- wp-content/themes/storefront/page.php
- wp-content/themes/storefront/404.php
- wp-content/themes/generatepress/header.php

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 · microsoft flags
Skill · vercel dashboard
Skill · nexu-io adding-mcp-store-servers
Skill · posthog mem-search
Skill · thedotmack smart-explore
Skill · thedotmack