WordPress Template Hierarchy Documentation

Template Hierarchy System

The WordPress template hierarchy is a rule-based system that determines which theme template file will be used for a specific request. When a visitor loads a page, WordPress identifies the type of content being requested—such as a page, post, category archive, or author archive—and then searches for the most specific matching template file. If a specific file does not exist, WordPress falls back step-by-step to more general templates until it finally uses index.php, which every theme must have.

Hierarchy Order

WordPress always looks for template files in a defined order, starting from the most specific and moving toward the most generic. The order changes depending on what is being requested.

Example: Page Template Lookup Order

• Custom template selected in the Page Attributes settings
• page-{slug}.php
• page-{id}.php
• page.php
• singular.php
• index.php

Example: Single Post Lookup Order

• single-post.php (rarely used)
• single.php
• singular.php
• index.php

File Naming Conventions

WordPress uses specific naming conventions so that theme files can match different types of content. File names often follow a pattern like:

• category.php
• single.php
• page.php
• archive.php
• home.php

For pages, WordPress allows two specialized naming patterns:

• page-{slug}.php — Uses the URL slug. Example: /about/team/ → page-team.php.
• page-{id}.php — Uses the page's numeric ID. This is permanent even if the slug changes.

The difference is that slug files follow the URL and will break if the slug is changed, while ID files follow the page record and continue working even if the title or URL changes.

Summary

The WordPress template hierarchy determines how a theme chooses the correct template file by following a predictable order—from the most specific match to the most general fallback. By using correct naming conventions such as page-{slug}.php and page-{id}.php, developers can create highly targeted templates for individual pages or groups of content. Understanding the hierarchy results in cleaner theme development and more flexible site layouts.