The WordPress Template HierarchyBy Tahir Taous
WordPress themes allow you to change the design of your website, providing control over the look and feel. They are essentially collections of different template files that work together and produce the overall design of your website.
Before you dive deeper into WordPress themes, it is important that you have an understanding of how WordPress operates and how the different pages of your website are created. WordPress interacts with a database to store your content. That means whenever you create a new post or page, the content of your post or page lives in a database and it’s only displayed using templates when the visitor asks for that particular content.
A WordPress theme is a collection of templates (CSS and PHP files) that WordPress uses to display the database content. WordPress will look for files in a theme to use to render the current page in a specific order. This is called a ‘template hierarchy’, that is used to create and extend WordPress themes.
WordPress themes decide how your content should be displayed on your website. A template in WordPress is a single file that determines what a specific page or set of pages look like on the front end of your website. When you change your theme, you are changing the way the content is displayed without changing the content itself.
WordPress themes use different templates files to generate a complete web page. For example, when you access a WordPress website, you can actually see multiple different template files combined together to create one complete page.
For instance, if you will look at an index page, like the front page of a blog, you will usually see a header created by the
header.php template, content created by
index.php, sidebar created by
sidebar.php and the footer created by
However, if you access a single page, you will still see the same header, same sidebar and same footer but the content would be created by
single.php instead. The question is how do you know which of these template files kick in and at what point? That’s where the WordPress template hierarchy comes in.
The WordPress template hierarchy determines in what order your template files are loaded within your WordPress theme. WordPress searches for these files, to determine how to load your site.
If you open the ‘Twenty Fifteen’ (one of the default WordPress themes) theme folder, there are more than 15 templates files. These include template files for 404, archive, author-bio, comments and content-link just to name a few. WordPress will use the Query String information contained within each link on your website to decide which template or set of templates will be used to display the page.
WordPress decides what type of page (search page, category page or home page for example) is being requested and then chooses the appropriate template suggested by the WordPress Template hierarchy to generate the content.
WordPress has a special and strict naming convention associated with theme files, so all themes share a fairly commonly named set of files in the back end. For example, to easily manage your content you can create
footer.php files. These template files must be named
WordPress looks for template files with specific names in the current theme’s directory to determine which template to use, most commonly the first matching template file is used. If WordPress cannot find a template file with a matching name, it skips down to the next file name in the hierarchy. If WordPress fails to find any matching template file, it will use index.php (the theme’s home page template file).
So when you are editing template files what you have to think about is what type of content this is, then edit the appropriate template file for that type of content. The same applies to when you’re creating WordPress themes from scratch.
Minimum Theme Requirements
The only files that are required for a WordPress theme to work are
index.php is the main and only file that will process every WordPress query, as well as the structure of the site.
The minimum files required for a WordPress theme to work and to be visible in the WordPress dashboard for activation are
style.css are missing, you will see following error.
The following themes are installed but are incomplete. Themes must have a style-sheet and a template.
This separation greatly increases efficiency. Combining everything into one big single file
index.php might technically work, but it wouldn’t be pretty, and would cause endless issues down the line. Also editing a theme would be a nightmare!
Here is the list of the theme files recognized by WordPress.
There are many other files as well, you can view the template files list for more details.
Twenty Fifteen Template Hierarchy Example
Suppose you have activated the Twenty Fifteen theme and a user visits the page
yoursite.com/author/tahir/. First, WordPress will search for the template labeled
author-tahir.php is not available. WordPress will then look for
author.php, if it also does not exist, it will look for
archive.php. This file is available in Twenty Fifteen theme. If you delete or rename
archive.php then WordPress will use
index.php to render the page.
Each time a user visits your website, WordPress moves up the template hierarchy until it finds a template file that matches. This has everything to do with how these files are named.
The ‘What The File’ Plugin
To find out what file and template WordPress is using to display page content you are currently viewing, you can use the very handy What The File Plugin. This is a free plugin developed by Barry Kooij.
This plugin adds an option to your toolbar showing what file and templates are being used. I installed the ‘What The File Plugin’ for testing purposes on my local server and found it worked great.
To test which files WordPress uses if a specific file isn’t available, I renamed two files (in the Twenty Fifteen Theme). In the screenshot below you can see which files WordPress uses to display content.
You can see the Twenty Fifteen theme uses the
content-search.php file to display search results. If you delete or rename
content-search.php, WordPress will use
content.php to display search results instead.
The ‘What The File’ plugin also allows you to click the file name directly to edit it through the theme editor. This plugin requires WordPress 3.1 or higher, it worked fine with WordPress 4.1 as well.
If you’re interested in learning more about the WordPress template hierarchy and theme development in general, I’d recommend the following resources: