If you are WordPress theme developers or using a child theme to modify your parent theme, it is reasonable to assume that you will reach a point where you will have to understand the hierarchy of WordPress themes.
This hierarchy dictates which template will be used to display different types of content. It takes into account all types of content, such as posts, pages, custom post types, and taxonomies, and beyond that allows you to create unique templates for specific pages.
However, this hierarchy can be somewhat confusing. For example, when looking at an archive of a taxonomy linked to a certain custom post type, which template file should we use? And how do templates work for individual posts?
In this post, we’ll take a look at that hierarchy in WordPress themes, explain how it works, and provide some examples. I hope that by the end of this guide, you will be able to create custom WordPress themes while maintaining a correct hierarchical structure.
Page Template Hierarchy – Types of Templates
If we try to describe simply – pages in WordPress are composed of different template files, and these can be called using the get_template_part function. Each file represents a different part of the page, and together they make up all the content for a specific page that you determine and define through the WordPress admin interface.
But the choice of which page template to use is based on that same robust hierarchy mentioned earlier, and in this hierarchy, the default template is replaced by a more specific template. I’m sure an example in this case will explain better…
Let’s say a user visits the page “http://domain.com/author/roee“. WordPress will first look for a page template (file) named author-roee.php. If this file does not exist, WordPress will search for a file named author.php. If that doesn’t exist either and we continue to move up the hierarchy, WordPress will search for archive.php, and then index.php to render and display the page.
Every time a user visits a specific page, WordPress moves up the hierarchy until it finds the appropriate file, as the filename, as you understood, carries significant meaning and determines whether to use that file or not, according to that same hierarchy we mentioned.
Essential Template Files
An important thing to know about WordPress themes is that there are files that must exist for a theme to work.
For example, the files index.php and style.css are mandatory. The first is the highest-level page template in the template hierarchy and will be used when WordPress does not find a more specific page template (more on that later).
The second is the required style sheet that contains basic information about the theme you are using, such as: theme name, description, and theme author. Since these two files are not page templates, we won’t delve into them too much, but it’s important to note that they exist.
If we exclude assets such as Javascript files and CSS files, we can say that all the files in the theme’s directory are such template files, and these are divided into two groups: those outside WordPress’s loop and those that contain WordPress’s loop.
WordPress’s loop exists to fetch content from the database (preserved through the admin interface) and render them into actual pages on your site.
We’ll explain more about the files that contain the loop later, but it’s important to mention those files outside WordPress’s loop as well.
When talking about files outside WordPress’s loop, I mean components on a page that are outside the main content of that page (those you enter when editing the content). These include the header and footer. The header contains the HTML and meta tags you want to add before the content, and the footer contains those after it.
The header file is called header.php and the footer file is called footer.php. These two files are essential for the theme, but they exist outside WordPress’s loop.
Another important template file is sidebar.php. This file is used for content that comes from outside the WordPress content editor. Often, it appears on the left or right side of the page, but it can actually appear anywhere you want. This is where themes typically display widgets and additional external information.
In addition, there is the comments.php file, which is responsible for those comments you find at the end of most of the posts you read. This file can be somewhat complex, but basically, it simply contains HTML and PHP code describing how the comments will appear on your WordPress site.
The files outside the loop are important, but the main structure of WordPress sites depends on those template files that contain the actual content, namely those inside WordPress’s loop.
The decision on which file WordPress uses depends on the hierarchical order of the template pages and the filenames in the theme you are using.
Front Page
It is reasonable to assume that the home page is one of the important pages in your theme. When a user visits your home page, WordPress will look for the index.php file to render the page.
However, the index.php file has a stronger significance than just rendering the home page. This file will be used in any situation where WordPress does not find a specific file for a certain template.
Archive pages, single pages (single.php), and similar pages will use the index.php file unless a more specific file is found in your theme. We’ll delve into this topic a bit more later, but for now, it’s important to remember that index.php is a vital and necessary file.
So, in any case, there are two files that affect the home page: home.php and front-page.php, with the latter having priority over the former. If the front-page.php file does not exist, WordPress will use home.php or page.php, depending on what you’ve set in Settings > Reading in the admin interface (either latest posts or a static page).
If one of these files exists in your theme, it will override the index.php file and take precedence when rendering the home page. However, remember that both index.php and front-page.php can contain the same code and render the home page exactly the same way.
Nevertheless, front-page.php will be used only for the home page, while index.php will be the default for other pages. So, the hierarchy for your home page will look like this, with the top file being more specific and preferred over those below:
/*** Homepage Hierarchy ***/
front-page.php
home.php
page.php
index.php
Archive Pages
Archive pages are pages that display a list of posts belonging to a certain “group.” These pages include author pages, category pages, date pages, and any other list of posts that makes sense to group together.
The default template for archive pages is the archive.php file. If there is no more specific template for these pages, the archive.php file will be used. This file is not truly necessary, and if it’s not found in your theme, WordPress will default to using index.php to render the archive pages.
However, it’s advisable to ensure that at least the archive.php file exists if there are no more specific files for such pages in your theme. Of course, even in this case, there are more specific templates deeper in the hierarchy that can be used to override the archive.php file.
The hierarchy for archive pages is quite simple:
/*** Archive Hierarchy ***/
archive.php
index.php
Author Page
Author pages are “sub-templates” of the archive template and only display a list of posts by a specific author. For example, a user can access “http://yoursite.co.il/author/username” to see all posts written by the author.
By default, WordPress will use the archive.php file for these pages. However, if you want to be more specific, you can create a file named author.php. If you do this, author pages will use the author.php file to render the page and override the archive.php file.
But in this case, you can be even more specific and add a file that will render the content differently for a specific author. This can be done by creating a file named author-[id].php or author-[nicename].php. In the example we presented above, we could create a file named author-roee.php to override both archive.php and author.php and display the content.
Author Page
The example of author pages is an excellent way to understand how the hierarchy in WordPress works:
/*** Author Hierarchy ***/
author-[nicename].php
author-[id].php
author.php
archive.php
index.php
Category Page
Category pages work in the same way as author pages. For example, if you visit “http://yoursite.com/category/my-category“, by default WordPress will use archive.php. However, if you create a file named category.php, it will override the default, and WordPress will use this file to render the page.
Similar to author pages, you can specify the category using category-[slug].php or category-[id].php. In both cases, these files will take precedence over category.php.
The hierarchy for category pages is the same as for author pages:
/*** Category Hierarchy ***/
category-[slug].php
category-[id].php
category.php
archive.php
index.php
Additional Archive Pages
I hope the examples above help you understand how the hierarchy of archive pages works. But this hierarchy is not relevant only for author and category pages; it works for any taxonomy in WordPress.
For example, if you want to create a template that is implemented only for tag pages, you can create a file named tag.php or even tag-[id].php if you want to go deeper in the hierarchy. Similarly, for date pages, you can create a file named date.php.
There is one exception when it comes to archives of Custom Post Types. Like other cases, archive.php will be the default file, but if you want to create a specific template for the archive page of a custom post type, you need to create a file in the following format: archive-[post_type_name].php.
Other than this exception, everything works exactly the same. If you want to see a complete list of file names or Naming Conventions for archive pages in general, take a look at the WordPress Codex.
Single Pages
Now that we understand how the hierarchy of archive pages works, let’s move on to single pages on a WordPress site. These include individual pages such as: static pages, single posts, attachment pages, and posts of custom post types.
Single Posts
Single posts refer to any individual page falling under the post type or custom post type you’ve created. The general template for these pages is the single.php file. If only this file exists in your theme, then all individual posts, including attachment pages and custom post types, would use this file as a template.
Note that this file is not mandatory – if it doesn’t exist, WordPress will use the
index.phpfile to render the content.
If you want to define a template for a specific custom post type, you can create a file named single-[post_type_name].php. For example, if the custom post type is called “Portfolio,” then the file name should be single-portfolio.php.
There is also an option to be more specific with attachment pages using the attachment.php file. Regarding attachment pages, you can even go deeper and set a template based on the type of file (MIME Type), for example, image.php or video.php.
/*** Single Post Hierarchy ***/
image.php (or video.php, text.php, etc.)
attachment.php
single-attachment.php
single-[post_type_name].php
single.php
index.php
Static Pages
Pages are a slightly different case. When I say pages, I mean all content under the “Pages” content type in WordPress. Like other content types, you have the option to set a default template named page.php. Even in this case, this file is not mandatory, and if it’s missing, WordPress will use the index.php file.
Unlike posts pages we mentioned earlier, for pages, you have the option to create a specific template for a particular page using page-[id].php or page-[slug].php. These templates will be used only for that specific page you’ve defined in the file name, whether by ID or slug. All other pages will use page.php.
However, in the case of pages, there’s the option to choose the page template through the “Page Attributes > Template” section in the page editing screen. If you select a template (Custom Template) in this section, it will override any other template existing for that page, making it the hierarchy’s priority.
The hierarchy of pages looks as follows:
/*** Page Hierarchy ***/
custom template
page-[slug].php
page-[id].php
page.php
index.php
Additional Page Templates
The templates we’ve covered in this guide cover almost all types of content on any WordPress site. However, there are two templates we haven’t mentioned yet. The first is 404.php, which will be displayed in case the page is not found or there’s an error in the URL.
The second template you might see sometimes is search.php. This template is responsible for displaying search results on your WordPress site. This can also be managed by the index.php file in certain themes.
Conclusion
The hierarchy of page templates in WordPress is like a reference. There’s a convention for file names that you need to follow, and it comes into play when you’re developing or customizing WordPress themes.
It’s reasonable to assume that in premium themes or themes built by such developers, you’ll also find that the template page itself is divided into files using the get_template_part() function mentioned at the beginning of the guide.
Nevertheless, I’m confident that after reading this guide, you’ll find that it’s quite simple to understand how WordPress theme hierarchies work, and more importantly, how you can make modifications to those theme hierarchies.
