Understanding The WordPress Template Hierarchy

Today’s article isn’t the same type of “How-To” that I write most of the time, but it’s a valuable lesson none the less.

A lot of the content here at Welcome To WordPress teaches you how to optimize and customize your blog, often by modifying your theme’s code. Whenever I write one of those articles I try to make sure I’m clear about what file needs to be modified – but what if you wanted to take something you’ve learned and apply it to a different part of your site?

That’s what today is all about. Understanding how WordPress builds each page of your blog from the files in your theme. When we’re done, you’ll have a better idea of where to start when you want to improve or modify something.

Basic WordPress Structure

The first thing to understand is that when WordPress displays a page on your blog it’s actually doing a whole lot of things at once. First, it’s reading and interpreting the URL that’s being requested to determine exactly what a visitor is looking for. This is how it knows if it’s displaying a post, a page, a category, a monthly archive – you get the idea.

Once it’s determined what specific piece of content your visitor is looking for, it loads different files provided by your theme to build the correct page. Generally speaking, each page of your WordPress site is built with one primary file – which then includes three other files.

The first file depends on what type of page it is. Something like index.php, category.php, page.php, or single.php, are a few examples.

Most of the time, each of these files will contain instructions to include three more files: header.php, footer.php, and sidebar.php (whose purposes should be self-explanatory).

Understanding Templates

Each of the files described above is referred to as a template. The files themselves don’t actually contain all of the text that displays on your blog (for example, the content of your posts isn’t written into single.php).

What the files DO contain are a series of instructions, written in PHP, that tell WordPress what to do. Different PHP tags indicate what should be displayed, while CSS and HTML control how it should look.

Once WordPress analyzes the URL of the page and knows what post your visitor is looking for, it runs through the code and finds instructions like:

“Display the post title, then grab the content of the post. After that, you need to list the categories that this post is in. Also, grab the URL for each of those categories so they can all be links. Then grab the date that the post was written…”

And so on. Obviously, those instructions are written in code and not plain English, but you get the idea. Think of it this way: your blog is like Mad Libs. The difference is that instead of filling in the blanks with nouns and adjectives, WordPress gets a bunch of code that it then fills in with your post content.

The Template Hierarchy: Knowing What Template To Look For

Okay, so if there’s something on your blog that you want to edit, how do you know what template you’re looking for? For that, you’ll want to become at least somewhat familiar with the Template Hierarchy.

WordPress is built so that it can have different files for different types of pages, some templates are designed to be used for a single, specific page while others are meant to be used for an entire group.

If the specific template for a certain page doesn’t exist, WordPress has a hierarchy in place so it can select a backup – this allows theme designers to keep things as simple (or advanced) as they want. In fact, a WordPress theme can function with only two files: index.php and style.css.

If no other files exist, everything defaults back to index.php.

Here’s how the hierarchy breaks down for some of the common types of pages on your blog:

• The Home Page

  home.php » index.php
  (the home.php file is only ever used on the home page of the site)

• The Posts Page

  index.php
  (Unless your posts are displayed on your homepage AND you have home.php)

• Single Posts

  single.php » index.php
  (In WordPress 3.0, a new template called single-posttype.php will be added as the primary template, allowing for the new post-type feature that will be added)

• Pages

  custom template » page-slug.php » page-id.php » page.php » index.php
  (Custom templates are selected on the “Edit Page” screen. The next two in this list are designed to be used on a specific page, and the slug/id of that page should be added into the file name – eg ‘page-privacy-policy.php’ or ‘page-63.php’)

• Categories

  category-slug.php » category-id.php » category.php » archives.php » index.php

• Author Pages

  author.php » index.php
  (WordPress 3.0 will also add author-nicename.php and author-id.php, allowing for custom templates for individual authors)

• Tag Pages

  tag-slug.php » tag-id.php » tag.php » archives.php » index.php

Additional Templates

The list above gives a breakdown of the more commonly used page types on a WordPress blog. There are, of course, more pages than the ones listed here, and those do have their own hierarchies.

You can find more information in the WordPress Codex on how the WordPress Template Hierarchy effects these other page types.