A Beginners Guide to the WordPress Template Hierarchy

A Beginner’s Guide to the WordPress Template Hierarchy, covering how the template hierarchy works, and how it affects both classic and block themes.

Learning outcomes

1. Understand how the Template Hierarchy works
2. Identify the different template types in the hierarchy
3. Follow the hierarchy for a specific content type

Comprehension questions

1. What is the ultimate fallback template in the hierarchy?
2. What are the three levels of template types in the hierarchy?
3. What determines if a template is a “variable” template type?

Transcript

Hey there, and welcome to Learn WordPress.

In this tutorial, you’re going to learn about the WordPress Template Hierarchy, and why it’s important to know if you’re developing a WordPress theme. In this video, we will cover:

• A brief overview of the WordPress Template Hierarchy
• How the Template Hierarchy works
• The Templates Types that make up the Template Hierarchy

Every WordPress theme is primarily made up of templates. Templates are what WordPress uses to generate the web pages on your WordPress site.

For example, whenever a WordPress post is displayed in the browser, the template to render posts is used. Similarly, whenever a page is displayed, the template to render pages is used.

However, a typical WordPress site doesn’t just have posts or pages, it might have other pages, like post archive lists, a 404 page, and a search results page. There might also be custom content types that need to be rendered differently, like a list of products, or an archive of posts by a specific author.

So how does WordPress know which templates to use, and when?

This is where the WordPress Template Hierarchy comes in. The Template Hierarchy is the system that WordPress uses to determine which template files should be used to render individual pages.
How the WordPress Follows the Template Hierarchy

When a user requests a WordPress page, it’s usually done by means of a permalink. Here is an example of the permalink to the archive page for a specific author

/author/nicename/

However, this permalink is actually translated by the webserver to something called a query string. This query string is what WordPress uses to determine what content to display.

So, the author archive page query string for the above permalink would look like this

/?author_name=admin

WordPress also uses the query string to decide which template or set of templates should be used to display the content for the page. When the WordPress page execution runs the query, it follows a process to search down through the template hierarchy until it finds a matching template file for the content.

To determine which template file to use, WordPress:

• Matches every query string to a query type to decide which page is being requested (for example, a search page, a category page, etc);
• Selects the template in the order determined by the template hierarchy;
• Looks for template files with specific names in the current theme’s directory and uses the first matching template file as specified by the hierarchy.

Let’s look at the above example of the author archive page, and follow the process.

Let’s say you have an author with the slug or nickname of johndoe, which has an ID of 3 stored in the database. On your site, you have a link to the Authors archive list, which is a list of all posts by that author. The URL for this list would typically look like this:

http://example.com/author/johndoe/

When WordPress translates that permalink into a query string and looks for the template to use to render the author archive list, it will follow the following process, determined by the template hierarchy.

• First, it will look for a template with the filename ‘author-johndoe’
• Then it will look for a template with the filename ‘author-3’
• Then it will look for a template with the file name ‘author’
• Then it will look for ‘archive’
• And then finally it will look for ‘index’

If it finds any of these templates in the active theme, it will use that to render the author archive list.

In Classic themes, your templates are PHP files, with a .php extension. In Block themes, they are HTML files, with a .html extension. Regardless of the type of file, the template files must match the naming convention of the template hierarchy, in order for WordPress to be able to find and use the right template.

The visual overview of the WordPress Template Hierarchy is a good way to understand the system.

On the far right, you’ll notice that there are a series of Primary Templates in purple. These templates are the core templates that every WordPress theme must have. This is because these are the default “fallback” templates that the template hierarchy will rely on, if none of the templates higher up exist.

As you can see the Archive, Single, Page, Home, 404, and Search templates are the fallbacks for any other templates higher up, while the index template is the ultimate fallback template.

If you’re creating a WordPress theme, it’s recommended to at least include these 7 primary templates.

Next, there are the secondary templates, in green. These are typically extensions of their primary counterparts but created for specific purposes. For example, author is an extension of archive, but for a specific archive of posts by an author.

Higher up, you have the variable templates, in orange. These are templates that are different, depending on the part of their file name that is variable.

So for example, you could have an author-johndoe template for all posts by johndoe, and then an author-janedoe template for all posts by janedoe. The two variable temples available for this would be the author-$id template and the author-$nicename template, where $id and $nicename are the variable part.

Finally, the visual overview also shows the page types in dark grey. Each type of page will have one or more templates along the hierarchy, all the way back down to the index template.

For more information on how the template hierarchy works, including the visual overview and detailed breakdown of each template along the hierarchy, visit the Template Hierarchy documentation, which is in the Theme Developer Handbook on WordPress.org, under Theme Basics