🗂️ Theme File Structure and Template Hierarchy

Themes: Presentation, Not Function

WordPress splits cleanly into two halves. WordPress core handles functionality and data: it stores posts in the database, runs the admin dashboard, and exposes an API of functions. A theme handles presentation: it decides how that content looks and where each piece appears on screen.

💡 A useful analogy: Think of WordPress core as the plumbing, wiring, and load-bearing walls of a house. The theme is the paint, the furniture, and the layout of each room. You can completely redecorate — swap themes — without touching the foundation or losing a single post.

This separation is the single most important idea in theme development. It tells you what belongs in a theme and, just as importantly, what does not.

Core supplies the data and the APIs; the theme decides how it all looks.

The Theme Directory

Every theme lives in its own folder inside /wp-content/themes/. Installing a theme means dropping a folder there; activating it happens under Appearance → Themes. Here is the anatomy of a typical classic (PHP) theme:

wp-content/
└── themes/
    ├── twentytwentyfour/          # A bundled default theme
    └── my-theme/                  # Your custom theme
        ├── style.css             # REQUIRED — metadata header + styles
        ├── index.php             # REQUIRED — universal fallback template
        ├── functions.php         # Theme setup, hooks, enqueues (mini-plugin)
        ├── header.php            # Opening HTML + site header
        ├── footer.php            # Site footer + closing HTML
        ├── sidebar.php           # Widget area
        ├── front-page.php        # The site's front page
        ├── home.php              # The blog posts index
        ├── single.php            # A single blog post
        ├── page.php              # A static page
        ├── archive.php           # Category/tag/date/author archives
        ├── search.php            # Search results
        ├── 404.php               # "Not found" page
        ├── comments.php          # Comment list + form
        ├── template-parts/       # Reusable fragments
        │   ├── content.php
        │   └── content-page.php
        ├── inc/                  # PHP includes (customizer, template tags)
        ├── assets/               # css/, js/, images/
        ├── screenshot.png        # 1200×900 thumbnail for the admin
        └── theme.json            # Global styles & settings (modern themes)

Only two of these files are strictly required. Everything else is an optional refinement that gives you more precise control — and cleaner code.

The Two Required Files

A theme that WordPress will recognize and activate needs exactly two files: style.css and index.php.

style.css — the identity card

Despite the name, this file does double duty. Its opening comment block is metadata that WordPress reads to display your theme in the admin. Below that comment you may add CSS, though larger themes usually enqueue separate stylesheets instead.

/*
Theme Name: My Theme
Theme URI: https://example.com/my-theme
Author: Ray de la Paz
Author URI: https://example.com
Description: A lean, modern classic theme.
Version: 1.0.0
Requires at least: 6.4
Tested up to: 6.7
Requires PHP: 8.2
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Text Domain: my-theme
Tags: blog, custom-menu, featured-images, translation-ready
*/

/* Optional theme styles below the header */
body {
    font-family: system-ui, sans-serif;
    line-height: 1.6;
}

index.php — the universal fallback

If WordPress can't find a more specific template, it always falls back to index.php. That guarantee is why it's required. A minimal but complete index.php looks like this:

<?php get_header(); ?>

<main id="primary" class="site-main">
    <?php
    if ( have_posts() ) :
        while ( have_posts() ) :
            the_post();
            ?>
            <article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
                <h2 class="entry-title">
                    <a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
                </h2>
                <div class="entry-content">
                    <?php the_content(); ?>
                </div>
            </article>
            <?php
        endwhile;
        the_posts_navigation();
    else :
        ?>
        <p><?php esc_html_e( 'Nothing found.', 'my-theme' ); ?></p>
        <?php
    endif;
    ?>
</main>

<?php get_sidebar(); ?>
<?php get_footer(); ?>

Notice this file no longer hand-writes the <html> and <head> tags — those move into header.php, pulled in by get_header(). That is the modular approach we'll explore below.

<?php
// functions.php — theme setup

function mytheme_setup() {
    add_theme_support( 'title-tag' );
    add_theme_support( 'post-thumbnails' );
    add_theme_support( 'html5', array( 'search-form', 'comment-form', 'gallery', 'caption' ) );
    add_theme_support( 'responsive-embeds' );

    register_nav_menus( array(
        'primary' => __( 'Primary Menu', 'my-theme' ),
        'footer'  => __( 'Footer Menu', 'my-theme' ),
    ) );
}
add_action( 'after_setup_theme', 'mytheme_setup' );

function mytheme_assets() {
    wp_enqueue_style( 'my-theme', get_stylesheet_uri(), array(), wp_get_theme()->get( 'Version' ) );
    wp_enqueue_script( 'my-theme-nav', get_theme_file_uri( 'assets/js/navigation.js' ), array(), '1.0.0', true );
}
add_action( 'wp_enqueue_scripts', 'mytheme_assets' );

The Template Hierarchy

Here is the core idea, and it's worth memorizing: for any request, WordPress looks for the most specific template file it can find, and falls back to more general ones until it lands on index.php.

💡 Think of hospital triage. WordPress first asks "what kind of request is this?" (a single post? a category? a 404?). Then, within that category, it looks for the most specialized template available before settling for a general one. You never write a template for a case that doesn't need special treatment — the fallbacks handle it.

The hierarchy branches by content type. This simplified flowchart shows the major branches and their fallbacks:

Every path eventually funnels down to index.php.

Tracing Real Requests

The best way to internalize the hierarchy is to trace concrete URLs. WordPress checks each template in order and stops at the first that exists.

Template Parts & Reuse

Copy-pasting the same post markup into index.php, single.php, and archive.php is a maintenance trap. WordPress solves this with get_template_part(), which pulls in a reusable fragment and — crucially — respects child themes and naming fallbacks.

<?php
// Load template-parts/content.php
get_template_part( 'template-parts/content' );

// Load template-parts/content-video.php, falling back to content.php
get_template_part( 'template-parts/content', 'video' );

// Pass data to the part (WordPress 5.5+)
get_template_part( 'template-parts/content', 'post', array(
    'featured' => true,
) );

A slimmed single.php then reads almost like an outline of the page:

<?php get_header(); ?>

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

        // content-post.php if it exists, else content.php
        get_template_part( 'template-parts/content', get_post_type() );

        if ( comments_open() || get_comments_number() ) {
            comments_template();
        }
    endwhile;
    ?>
</main>

<?php get_sidebar(); ?>
<?php get_footer(); ?>

Inside the part, you read passed data from the $args array:

<?php
// template-parts/content.php
$args = wp_parse_args( $args ?? array(), array( 'featured' => false ) );
?>
<article id="post-<?php the_ID(); ?>" <?php post_class( $args['featured'] ? 'is-featured' : '' ); ?>>
    <?php the_title( '<h2 class="entry-title">', '</h2>' ); ?>
    <div class="entry-content"><?php the_excerpt(); ?></div>
</article>

Child Themes

Suppose you love a theme but want to tweak its header and colors. Edit the theme directly and the next update overwrites your work. The fix is a child theme: a separate theme that inherits everything from a parent and overrides only what you change.

💡 It's inheritance. A child theme is to its parent what a subclass is to a base class: it keeps all the parent's behavior for free and overrides individual methods (here, template files) as needed.

A child theme needs a folder and a style.css with a Template line pointing at the parent's folder name:

/*
Theme Name: Twenty Twenty-Four Child
Template: twentytwentyfour
Version: 1.0.0
Text Domain: twentytwentyfour-child
*/

The Template value must match the parent folder exactly. Then load both stylesheets from the child's functions.php:

<?php
function child_enqueue_styles() {
    // Parent stylesheet
    wp_enqueue_style(
        'parent-style',
        get_template_directory_uri() . '/style.css',
        array(),
        wp_get_theme( get_template() )->get( 'Version' )
    );
    // Child stylesheet, dependent on the parent
    wp_enqueue_style(
        'child-style',
        get_stylesheet_uri(),
        array( 'parent-style' ),
        wp_get_theme()->get( 'Version' )
    );
}
add_action( 'wp_enqueue_scripts', 'child_enqueue_styles' );

To override any template — say the header — copy the parent's header.php into the child folder and edit it. WordPress uses the child's version automatically. The same works for template parts: a child's template-parts/content.php transparently replaces the parent's.

Hands-on Exercise

<!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(); ?>
<header class="site-header">
    <a href="<?php echo esc_url( home_url( '/' ) ); ?>"><?php bloginfo( 'name' ); ?></a>
</header>

Best Practices

Summary & Quiz

📚 Further Reading

• Theme Handbook — Template Hierarchy
• Theme Handbook — Template Files
• Theme Handbook — Child Themes

🚀 What's Next?

Now that you know which template file runs, the next lesson dives into what goes inside it: The WordPress Loop — the engine that pulls your posts out of the database and displays them.