Introduction

The WordPress Template Hierarchy is like a detailed roadmap that WordPress follows to decide which template file to use. Think of it as a sophisticated decision tree - WordPress starts at the top with the most specific template and works its way down to more general ones until it finds a file that exists.

Understanding the Hierarchy

The template hierarchy is WordPress's way of being flexible yet predictable. It's like having multiple backup plans:

Homepage Display Hierarchy

The homepage has its own special hierarchy depending on your Settings → Reading configuration:

Single Post Type Hierarchy

When displaying a single post, page, or custom post type, WordPress follows this hierarchy:

Archive Page Hierarchy

Archive pages (categories, tags, dates, authors) have their own hierarchy:

<?php
// Example: Creating a specific category template
// File: category-tutorials.php

get_header(); ?>

<div class="tutorials-archive">
    <header class="archive-header">
        <h1 class="archive-title">
            <?php single_cat_title( 'Tutorials: ' ); ?>
        </h1>
        <div class="archive-description">
            <?php echo category_description(); ?>
        </div>
    </header>
    
    <div class="tutorial-grid">
        <?php
        if ( have_posts() ) :
            while ( have_posts() ) : the_post();
                // Custom layout for tutorials
                get_template_part( 'template-parts/content', 'tutorial' );
            endwhile;
            
            the_posts_pagination();
        else :
            get_template_part( 'template-parts/content', 'none' );
        endif;
        ?>
    </div>
</div>

<?php
get_sidebar( 'tutorials' );
get_footer();

Conditional Tags

WordPress provides conditional tags to check what type of page is being displayed. These are essential for controlling template logic:

<?php
// Using conditional tags in templates

// Check multiple conditions
if ( is_front_page() && is_home() ) {
    // Default homepage (showing latest posts)
} elseif ( is_front_page() ) {
    // Static homepage
} elseif ( is_home() ) {
    // Blog page (when not front page)
}

// Check for specific pages
if ( is_page( 'about' ) ) {
    // Page with slug "about"
} elseif ( is_page( 42 ) ) {
    // Page with ID 42
} elseif ( is_page( array( 'about', 'team', 'contact' ) ) ) {
    // Any of these pages
}

// Check post types
if ( is_singular( 'product' ) ) {
    // Single product post type
} elseif ( is_post_type_archive( 'product' ) ) {
    // Product archive page
}

// Combine conditions
if ( is_single() && ! is_attachment() ) {
    // Single post but not attachment
}

if ( is_archive() && ! is_category() && ! is_tag() ) {
    // Archive but not category or tag
}

Custom Page Templates

You can create custom templates for specific pages that override the normal hierarchy:

<?php
/**
 * Template Name: Full Width Layout
 * Template Post Type: page, post
 *
 * @package My_Theme
 */

get_header(); ?>

<div class="full-width-container">
    <?php
    while ( have_posts() ) :
        the_post();
        ?>
        <article id="post-<?php the_ID(); ?>" <?php post_class( 'full-width' ); ?>>
            <header class="entry-header">
                <?php the_title( '<h1 class="entry-title">', '</h1>' ); ?>
            </header>
            
            <div class="entry-content">
                <?php
                the_content();
                
                wp_link_pages( array(
                    'before' => '<div class="page-links">' . __( 'Pages:', 'my-theme' ),
                    'after'  => '</div>',
                ) );
                ?>
            </div>
        </article>
        <?php
    endwhile;
    ?>
</div>

<?php get_footer(); ?>

Debugging Template Loading

When templates aren't loading as expected, use these debugging techniques:

<?php
// Add to functions.php for debugging

// Show which template is being used
add_action( 'wp_head', 'show_template_file' );
function show_template_file() {
    if ( current_user_can( 'manage_options' ) ) {
        global $template;
        echo '<!-- Template: ' . basename( $template ) . ' -->';
    }
}

// Display all conditional tags
add_action( 'wp_footer', 'debug_conditional_tags' );
function debug_conditional_tags() {
    if ( ! WP_DEBUG ) return;
    ?>
    <div style="background: #f0f0f0; padding: 20px; margin: 20px;">
        <h3>Active Conditional Tags:</h3>
        <ul>
            <li>is_home(): <?php var_dump( is_home() ); ?></li>
            <li>is_front_page(): <?php var_dump( is_front_page() ); ?></li>
            <li>is_single(): <?php var_dump( is_single() ); ?></li>
            <li>is_page(): <?php var_dump( is_page() ); ?></li>
            <li>is_archive(): <?php var_dump( is_archive() ); ?></li>
            <li>is_category(): <?php var_dump( is_category() ); ?></li>
            <li>is_tag(): <?php var_dump( is_tag() ); ?></li>
            <li>is_author(): <?php var_dump( is_author() ); ?></li>
            <li>is_search(): <?php var_dump( is_search() ); ?></li>
            <li>is_404(): <?php var_dump( is_404() ); ?></li>
        </ul>
    </div>
    <?php
}

// Use Query Monitor plugin for detailed template info
// Or use this simple function
function get_current_template() {
    global $template;
    return basename( $template );
}

Special Cases in the Hierarchy

Practice Exercise

Let's practice working with the template hierarchy: