Understanding the WordPress Template Hierarchy


One of the simpler and more powerful concepts that runs underneath WordPress themes is that of the template hierarchy. It’s super powerful and can make your life much easier as you build out a theme for your site. And it’s not all that complex, so once you get the idea you’ll find working on themes much easier.

The Problem that Leads to the Hierarchy

WordPress wants to solve two problems with its themes: make them easy to customize and hard to break.

Broadly, WordPress wants to solve two problems with its themes: make them easy to customize and hard to break. Obviously both of these are part of what makes WordPress great — its themes end up having both of those qualities — but balancing them is something that takes some thought and insight.

To make themes hard to break, WordPress makes it such that every template for every page on the site uses the same structure — the concept of The Loop, about which I’ve written an introduction if you’re curious. This abstraction makes it easy for WordPress to know with a fair certainty that any given template file can render any given content.

This dependence on The Loop — which should always exist in the index.php file of your WordPress theme — allows WordPress to use it anytime it doesn’t have a more fitting file to use to render the page content it needs to. This is why a WordPress theme is hard to break — because even for obscure new content types WordPress will always be able to count on that index.php file being there to catch and render it.

To make WordPress easy to customize, WordPress has built up a large choice-tree on top of index.php. It can take it for granted that index.php will be there: but it’ll try to find a better template file to use if it exists. This means that if I want to change the page layout for when I have a single post, for example, I can just make a file called single.php, with The Loop inside of it, and WordPress will use that when it thinks there’s only one post on the page. This is powerful.

The Dynamics of the Template Hierarchy

WP_CheatSheet_TemplateMapAs we’ve said, WordPress has built up — using the concepts of The Loop, and it’s certainty that it can always fall back to index.php if it needs to — into some really powerful choice trees. Let say you want to customize the way your category archive — the listing of multiple posts from a single category — will look. If you’ve got an index.php in place, the first option you have is that you could use archive.php. This is the template that WordPress uses for any archive, so you could customize that if you also want this view to be used when your visitor clicks onto tags or month archives as well.

If you don’t like that, we can then continue down the path: the next option is that we can make a category.php. This is the one we want for the project I described at the outset: it’ll be used for any category archive, but only for a category one. Month or tag or any other type of archive will not use it, but all categories will.

But if you now decide that not only do you want most of your categories to use it, but you’d like some special category to look different than that — we’ll use Poems as an example — you’ve got a few more options. You can create a new template file as category-poems.php or, if you figure out the category number, category-32.php, and WordPress will use that to render the view when someone click a link to your poetry category.

This simple dynamic is, as you may be able to imagine, really powerful. Customization and improvements can be made on the fly as you build out a WordPress theme. Start with a simple index.php, get it set up just how you like, and then tweak it for all the different ways that WordPress will possibly find itself displaying your content.

Seeing the Whole Hierarchy

Once you understand this concept, making WordPress themes that benefit from this knowledge is simply a matter of filling out your knowledge of the specific template file you can make to replace the way your theme template hierarchy is currently cascade and which file you can replace.

Listing out the specific layout of each tree that WordPress looks at for each type isn’t all that useful here, so I’ll refrain. I promise it’d only bore both of use. But there are a few exemplary ways to see and understand this data when you need to reference it, so I’ll point you to them for further study:

  • Template Hierarchy on the WordPress Codex: The Codex is the canonical source for all your information about WordPress. Learn to love it. The page is quite long and detailed, which makes for somewhat dull reading, but makes it super valuable as a reference. You can easily CMD/CTRL+F for whatever you specific problem is — “single taxonomy” for example — and quickly find a great explanation.
  • WPTuts+ Cheat Sheet: Especially if you understand the basic terminology and function of WordPress functions like is_home() I really appreciate the brevity of their visual map. It’s not exhaustive, but it’s easy to read. (It’s also the image in the previous section.)
  • Marktime Media’s Graphical Version: These are a bit large and unwieldy for many contexts, but they’re really thorough and rather nice-looking to boot. If you’re a real WordPress nerd you could even use them as your desktop background.

About David Hayes

David likes learning, solving hard problems, and teaching. He bikes a lot, and lives in (and loves) Colorado. You can find him on Twitter as @davidbhayes and check out his latest hobby-project, Quodid, a monument to his love for pithy bits of wisdom.

13 thoughts on “Understanding the WordPress Template Hierarchy

  1. Pingback: Make Your Themes Better by Getting to Know get_template_part() | WPShout.com

  2. Pingback: The Three Core Concepts of WordPress Themes | WPShout.com

  3. Pingback: What You Need to Know About WordPress Custom Page Templates | WPShout.com

  4. Pingback: Guide to Understanding the WordPress Template Hierarchy | WPShout.com

  5. Pingback: Guide to Understanding the WordPress Template Hierarchy - WordPress News

  6. Pingback: WordPress Basics: Understanding And Making the Best Use of Your functions.php File | WPShout.com

  7. Pingback: WordPress's Conditional Tags | WPShout.com

  8. Pingback: Hacking The WordPress Template Hierarchy | WPShout.com

Leave a Reply

Your email address will not be published. Required fields are marked *