WordPress Template Hierarchy: The Complete Guide

One of WordPress’ best features is its powerful templating capabilities. By manipulating a handful of files, you can create complex themes with different layouts and visual options for different types of content. This is made possible by WordPress’ complex template hierarchy which gives the designer immense control over content presentation and layouts.

In this tutorial, we’ll learn about the WordPress template hierarchy, how it works, and how it affects your blog. To learn more about creating custom templates and themes, check out this course on WordPress theme selection and customization.

What is Template Hierarchy in WordPress?

To understand template hierarchies, we must first understand how WordPress renders pages.

Let’s consider that you have a WordPress blog, CoolBlog.com. You want to access a certain page on your blog with the URL:

http://coolblog.com/category/cool-posts/

When you type this URL into your browser, WordPress will swing into action to determine what type of page is being requested. WordPress has different pages for different content types – an archive page, a home page, a search page, etc. Once WordPress determines the page-type, it will try to find a template for that particular page.

In this example, WordPress knows that you are requesting a category page (since there is a /category/ right in the URL). But you aren’t requesting just any category page – you are requesting a specific category, cool-posts. Thus, WordPress will try to find a template that corresponds to this specific category.

Let’s break this down into individual steps:

1. WordPress will first look for a template for that particular category. Each category has a unique ID. In the above example, if the category ID is 5, it will try to find a template file named category-5.php

2. If WordPress can’t find the category-5.php file, it will move up one level and use the category.php template to render the page.

3. If the category.php template isn’t available, WordPress will use the archive.php template (since a category is nothing but a specific type of archive).

4. If archive.php can’t be found, it will fall back on the default index.php template.

Thus, the progression is from specific to general templates. For the above example, this can be represented as follows:

There are different hierarchies for different page types. For example, if you have your website front page at CoolBlog.com, WordPress will take the following path to determine which template to use:

1. WordPress will first look for front-page.php template which will serve as the front page.

2. If WordPress can’t find front-page.php, it will look for the template for the next level – home.php.

3. If it can’t find home.php, it will finally resort to using the default index.php.

No matter the content type, WordPress will always use index.php if it can’t find any other template. This means that you could have a fully functional (albeit with poor usability) website with just the index.php template file.

New to WordPress? Learn how to use this incredible blogging software with a course on WordPress for beginners.

WordPress Template Hierarchy by Content Type

WordPress can automatically detect what content type needs to be shown and search for the appropriate content type. Below, we’ll take a look at the hierarchies for a few selected content-types:

Category Pages

As mentioned above, a category is a special type of archive. WordPress utilizes the following hierarchy when displaying category pages:

1. If you have a specific category slug or name (say, cool-posts.php), WordPress will make use of it first. You can edit category slugs in the category page in your WP dashboard.

2. Each category also has a category ID, regardless of whether you’ve given it a slug or not. WordPress creates the category ID automatically. If WP can’t find the category slug, it will use the category ID next, like category-32.php

3. If the category ID template is missing, WordPress will use the default category.php template.

4. If it can’t find a category template, it will use the basic archive.php template.

5. If it can’t find even the archive.php template, it will turn to the index.php template.

The path is as follows:

category-slug.php  category-ID.php  category.php  archive.php  index.php

Author Pages

For author pages, WordPress takes the following path:

1. The first template WordPress will look for is the author name, like author-john.php

2. If it can’t find the author name, it will look for the author ID template (like author-2.php). Like category ID, WordPress generates the category ID automatically as well.

3. If the author-id.php template is missing, it will use a generic author.php template.

4. If even the author.php template is missing, it will use the basic archive.php template. Remember that author page is also a type of archive.

5. Finally, WordPress will turn to the index.php if it can’t find even the archive.php template.

This can be represented as follows:

author-name.php  author-id.php  author.php  archive.php  index.php

Want to create and sell your own WordPress themes? These course will teach you how to build WordPress themes from scratch!

Single Pages and Posts

So far, we’ve looked at archive content type. What about single pages and individual blog posts?

This is the hierarchy for standard single blog posts:

1. For a standard single blog post, WordPress will first try to find the single-post.php template.

2. If this is missing, it will turn to the generic single.php template.

3. If even single.php is missing, it will use index.php

single-post.php  single.php  index.php

But what if you have a custom blog post? In this case, WordPress will first look for a custom template, single-posttype.php, like this:

single-posttype.php -> single.php -> index.php

The hierarcy for single static pages, however, is slightly different:

1. WordPress will first see if you are using a custom template for the static page. This will be custom.php.

2. If you are using the default template, it will turn to the page-slug.php template.

3. Next, it’ll turn to the page-id.php template.

4. The next template will be page.php

5. Finally, it’ll use index.php

custom.php  page-slug.php  page-id.php  page.php  index.php

The WordPress documentation has a nice flowchart of the template hierarchy for different content-types.

You can find a high-resolution image here.

Conclusion

WordPress gives you immense control over the visual presentation of different content types. By creating custom templates for specific content-types, you can completely alter the look of your website. This is great for theme designers, coders and even lay users who want a high-degree of control over their blog’s presentation.

To learn more about WP templates, check out this course to build your own WordPress themes.