The WordPress Template Hierarchy
A visual guide, updated for WordPress 4.8.
How to use this table
Start on the appropriate Entry Point and move along the row from left (more specific) to right (more general) to understand the template hierarchy for the page that needs to be displayed.
For the more general templates, look to the left of the cell to understand which types of pages fall back to that template if more specific ones are not implemented in your theme.
|Entry Point||WordPress uses a series of checks (Conditional Tags) to decide what kind of page needs to be displayed|
|Variable template file name||Includes some aspect of the page to display|
|Constant template file name||Does not depend on any aspect of the page to display|
|Conditional||If a certain condition is met, the template is applied; see footnotes for explanations.|
|Base template||The last template in a chain, it must exist in your theme.|
|Archive Pages||Date Archive||date.php||archive.php||index.php6|
|Custom Taxonomy Archive2||taxonomy-$taxonomy-$term_slug.php1||taxonomy-$taxonomy.php||taxonomy.php|
|Custom Post Type Archive||archive-$post_type.php|
|Singular Pages||Attachment Post||$type-$subtype.php3||$subtype.php3||$type.php3||attachment.php3||single-$post_type-$slug.php1||single-$post_type.php||single.php||singular.php|
|Single Post||Custom Page Template4|
|Other Pages||Search Results||search.php|
|Front Page||Front Page||front-page.php||Home Page or Single Page5|
|Embedded Content||oEmbed Post||embed-$post_type-$post_format.php||embed-$post_type.php||embed.php||theme-compat/embed.php|
I built this chart by looking through the WordPress source code:
template-loader.php— decides the template hierarchy based on Conditional Tags
template.phpimplements a variety of methods to get a template hierarchy for specific kinds of pages (archive page, singular page, etc.)
1 WordPress stores the $slug in url-encoded format, with special characters encoded as %XY. For example, the thinking face emoji character (🤔) is encoded as %F0%9F%A4%94. As of version 4.7, WordPress will first try to match the decoded variant (e.g. 🤔.php), then the encoded one (e.g. %F0%9F%A4%94.php).
2 The post's format is considered a custom taxonomy, whose slug is post_format, and whose terms are post-format-link, post-format-quote, etc.
3 Attachment-related templates don't follow a logic hierarchy from more specific to less specific. You can handle these in the single-attachment.php template instead.
4 If the page has a Custom Page Template assigned to it, that template will be used. As of version 4.7, Custom Page Templates can be applied to all types of posts, not just Pages.
5 The user can configure what to show on the Front Page: either the content of the Home Page, or that of a specific page in the website.
6 The index.php file is technically not necessary for the hierarchy (as long as you have templates to cover all cases), but you still need to have one for the theme to be valid.