We recently released Up and Running, which we think is one of the best places a user, designer, or non-WordPress developer can start to get their mind around the concepts of WordPress development. One of the topics that the book covers well that we’d never covered at length on the site is the template hierarchy. The template hierarchy is the codified way that WordPress interacts with your theme.
Our posts here on Shout over the years have touched on the topic — see David’s favorite hack, or Josh’s explanation of overriding it, but this chapter from the Up and Running text is most thorough and complete version of that information we’ve put together. Enjoy!
Remember our factory analogy? WordPress is a factory that processes raw material, posts, into finished products, webpages.
So here’s where we are in the production process: a bundle of posts has been fetched out of the warehouse (the database), and they’re all ready to be painted and made to display beautifully by our paint room, the WordPress theme.
However, the theme provides a lot of possible lines to send those posts down: our different PHP templates. Putting our posts through index.php will result in a webpage that looks one way; putting it through home.php, archive.php, or page.php will give very different results.
The WordPress template hierarchy specifies which line to send a given bundle of posts down, based on properties of the bundle itself.
index.php: The Ultimate Fallback
For the factory to work, there must always be a line that can take the bundle of posts. This is why every WordPress theme must have an index.php template file.
So WordPress can always “paint” a webpage with index.php if it doesn’t have a more fitting template file to use. However, it will try to find a better template file to use if it exists.
The Rest of the Hierarchy
WordPress has created some really powerful choice trees for deciding which template to display. From the Codex:
The WordPress Template Hierarchy
To see what’s going on, let’s follow an example page from left to right on the diagram.
Tracing a Site’s “About Us” Page Through the Template Hierarchy
Let’s see what happens for an imaginary site’s “About Us” page, written as a Page-type post and located at site.com/about.
Page Type: Singular Page
Starting from the left: what’s our “page type”? This question really means, “What kind of bundle of posts are we dealing with?” The answer is “Singular Page,” because the warehouse has sent us only a single (“singular”) post, rather than lots of posts together.
Static Page
Next up, is this a “Single Post Page” or a “Static Page”? Don’t let the language confuse you: what they’re really asking is, “Is this a single post of type Post (like a blog post), or a single post of type Page (like an About page)?” It’s the second one, which they’re calling a “Static Page.”
Page Template: Default Template
Okay, are we using a custom template or a default template? We’ll get into custom templates later, in the “What You Need to Know About WordPress Custom Page Templates” chapter. You can read this as, “Did you select something other than Default Template in the Page Editor?”
Custom page templates
In this case, let’s say we don’t have a custom “About” template. That leaves us with “default templates.”
Template Used: page.php, with index.php Fallback
The next two nodes—page-$slug.php and page-$id.php—are little-used options that let you create templates for individual pages. We don’t have those, so we’ll skate right through them.
That leaves us with the template that will really display our About page: page.php. And if our theme doesn’t have page.php, we’ll slide all the way back to our ultimate fallback: index.php.
A Second Example: The Blog Index
Let’s take a second trip through the template hierarchy, this time with the site’s blog index page. Which webpage is this? It depends on your site’s settings in Settings > Reading:
If you leave the setting as it is, then your blog index is your site’s homepage: the webpage you see when you navigate to mysite.com. However, you can also set your blog index to appear at the URL of an existing “static page” (meaning, again, a Page-type post).
Choosing a “static page” for your blog index page will change the blog index’s URL to something like mysite.com/blog, for a Page titled “Blog,” or mysite.com/news, for a Page titled “News.”
Whatever webpage your blog index is, WordPress knows when you’re visiting it. That makes WordPress fetch a bundle of your most recent posts. When this bundle hits the template hierarchy—starting from the left of the diagram—the hierarchy recognizes your “Page Type” as “Blog Posts Index Page.”
Template Used: home.php, with index.php Fallback
As you can see, this tree is simple: your blog index page will display the contents of home.php, and, if that doesn’t exist, it’ll default back to good old index.php.
Seeing the Whole Hierarchy
Are you starting to get how the template hierarchy works? Once you understand the basic concept, making WordPress themes that benefit from this knowledge simply requires creating and modifying the proper template files for the types of webpages you wish to affect.
The diagram above is great, but there are a few other great ways to visualize and understand the template hierarchy:
- Template Hierarchy on the WordPress Codex: The Codex is the canonical source for information on the template hierarchy, and on WordPress itself—learn to love it! This is where you can learn what each type of template file does.
- WPHierarchy.com: This is an interactive version of the Codex’s template hierarchy image. Click on any node to get help understanding what it means and when it applies!
- WPTuts+ Cheat Sheet: Especially if you understand WordPress conditional functions like
is_home()(see WordPress’s Conditional Tags), we really appreciate the brevity of their visual map. It’s not exhaustive, but it’s easy to read.
Now You Understand the Template Hierarchy
The WordPress template hierarchy is a major part of the magic of WordPress themes. Now that you understand its basic workings, you can really dive in and understand exactly which templates apply in which cases.
Get Rid of the Guesswork with Show Current Template
One final recommendation: If you ever get stuck knowing which template is operating on a particular webpage, you can install a plugin: Show Current Template. When you browse the site while logged-in, it prints the current template into your admin bar, as follows:
Show Current Template indicates that this webpage is using the active theme’s category.php (top right of picture).
This plugin can be a great way to learn the template hierarchy in depth, as you see exactly which template is active at each part of your site.