This tutorial will teach you the essentials about wordpress template files and their hierarchy when hacking your theme.

This post is part of 30 WordPress hacks in 30 days.

In my last WordPress Hack Templates for Alternate Sidebar Layouts I touched on how you can create a theme template file for a page that has different sidebars for the rest of your blog. Answering some questions and comments for that article showed me that I need to write a more in-depth article about how the WordPress Template Hierarchy Works and the choices you have available to your when you create custom template files. This article should change the way you think about your WordPress theme FOREVER!

WordPress is a blogging system that has greatly evolved over. It’s evolved as much as bloggers and blogging itself has. Now, you can use it as a full fledged “Content Management System”, you can even use it to create a static web site with no blog at all. I would say that most of us use it as a blog, where the home page has a running “list of posts” from the newest to oldest. You can add those posts to “categories”, and now with WordPress 2.3x+ you can also “tag” them.

I’m going to explain to your how WordPress works “out of the box”. Keep in mind that this blog has been heavily customized, and I don’t even have blog posts on my homepage anymore – I’ve moved them to “/blog” on this site (which is something you can change in your WordPress dashboard under “Settings”).

When a web browser visits a WordPress blog, the software looks in your theme directory (/wp-content/theme) for the assigned theme. It’s either “default” (out of the box), or a custom one that you picked out and uploaded to your theme directory. WordPress then iterates through your theme files looking for which one to use in a specific order. That search order might change depending on what WordPress has been asked to do (show the homepage, show a category page, show search results, show an archive page, etc.). Your understanding of this search order (called the “template hierarchy”) is vitally important to your understanding of how WordPress Themes work. If you understand the template hierarchy in WordPress, you can build custom theme template files and make your blog 100 times more effective, indexable (by search engines), and in the end more profitable.

The WordPress Codex has an image of the template hierarchy that spells it all out. Since that is too big for this page, I created a custom one that is a bit more simplistic for display here:

what page template hierarchy wordpress

When I said “simplistic”, I really meant it – didn’t I? As the pictures shows, when a web browser calls a site with WordPress installed it asks itself “which (template) page do I need (to show the content)?” I’ll explain these php files in depth in a few minutes, but first generally WordPress asks, is it a date.php (archive) page, is it a category page, is it a tag page, is it the “home” (or blog) page, is it a single (post) page, is it a WordPress “page” (that you wrote), is it an error 404 (page not found) or seach page, and last is it some kind of attachment. You can see in the examples that if the right file is not found, with the exception of attachments, WordPress will just default to the index.php to display what it needs.

The WordPress Home Page template or “home.php”

Now, let’s dig a little deeper – shall we? Let’s say that you want to customize your “home” page of your WordPress blog – the one that by default shows your blog posts. MOST themes I’ve dealt with just use “index.php” to show your home page content. But if you look at the template hierarchy you see that the first page WordPress looks for (for the home page) is “home.php”. Your theme may or may not contain this file. If you don’t have one, just open index.php and “save as” home.php – customize it to your liking and now you have a custom theme home page template file. If you want your blog posts to be somewhere else other than your “home” page you will need to create a different template file for a “page” (instructions below), and then assign that “page” the proper template in “Manage->Pages-Pagename” in your WordPress dashboard. Then delete “home.php” and in your WordPress dashboard “Settings”, assign a different page to home to display what you want.

You should also read WordPress Hack #1: Query Posts, and WordPress Hack #15: 12 Ways to Hack Your Home Page.

WordPress Category Template Pages

When you write a post you can assign it to a “category”, which is one way of organizing your content. It’s also a way for your visitors to filter through your past content. When your categories are listed in your sidebar, and you click on one, WordPress will filter and show only posts that were assigned to that category. This is very handy. WordPress has two ways it can show you post content on pages like this, one is an “excerpt” and the other is the full post. Either way – you have some of the same content listed on this page as you do your (blog) home page, your archive (past post) pages, and (if you’re using them) also tag pages. This is a horrible, horrible thing to google as they see “duplicate content”. That means that all your pages (while useful to visitors) like this probably won’t be indexed by google and may even count against you.

Now, when it comes to google, and search engines in general – the object is to get as many pages as you can indexed. The more pages indexed, the more chances you have of somebody finding your blog. Most themes that I’ve seen don’t have any category page at all and just index.php is used to display category content. This is ok as a category.php file would be used for every single category you have added content too. If you want “original content” on each and every category page then you will need to create a template file for each and every catetgory you have created (I hope you haven’t gone wild).

If your WordPress dashboard go to “Manage->Categories”. If you put your mouse over any category name (without clicking), in the bottom of your web browser in the status bar will appear the “category ID”.

category ID example wordpress

If your theme doesn’t have a “category.php” file (if it does – use it), open up your “index.php” file and “save as “category-18.php” (using your category ID of course), and create one category template file for each category you have in your blog. In each file add a few paragraphs of original content to each category file, and then when search engines come around to index you – you’ll have some original content on each and every category page!!

Also, see this as an opportunity (not work). Why? Because it’s an opportunity to make more money. You can place different relevant targeted niche ads on each and every category page! Look at home many additional monetization opportunities you just created!

Regarding Category Templates, you should also read WordPress Theme Hack: Show Category Images, and WordPress Hack: 9 Things You can do with Categories.

WordPress Tag Template Pages

WordPress Template Tag pages work the exact same way as category template pages, with the exception that they use the “slug” (tag keywords) instead of the ID (I don’t know why category template can’t do this too!). So, if you tagged a post “wordpress hacks”, then your tag template file would be “tag-wordpress-hacks.php”. In the organization of a blog, categories should be very broad, and tags should be descriptive. A good example of a category would be “news”, or “code”. Tags could be “9-11” or “css web design”. That’s why optimally you should have maybe a dozen or two categories, but you might have hundreds (even thousands!) or tags. Since I’ve had the same categories since this blog started, but I add new tags all the time – I probably won’t create a custom tag template page for every tag I have. I WILL, however, create one for all the tags I feel are most-used, most-important, and most-monetizable!

You should also read WordPress Hack #15: Hacking WordPress Tags.

WordPress Author Template Pages

This is a template page I seldom see used, because most blogs have one author. Many blogs though have multiple contributors and authors – and each post can have an “authored by” link which takes them to the author page. If “author.php” doesn’t exist, index.php will be used by default.

The author.php page can list pages written by that author, all authors, it can list the authors – and be customize any number of ways. As I said, most themes don’t have this – but if you want a blog with multiple authors you probably want to create a custom author page. For more information on what’s possible read the WordPress Codex page on Author Templates.

WordPress Single Post Page Templates

When you write a post in WordPress, it’s gets listed on your home (blog) page, your archive page, and the appropriate category and tag pages. But is also has it’s own (full) page, which is what we call the “single.php” or single post page. Nearly every theme has a single.php file, but if it doesn’t then (of course) the single post is displayed using the default index.php theme file.

If your theme doesn’t have a “single.php” create one (based on index.php), if it does – consider customizing it. If you use Adsense I think that the single post is a great place to add a 336×280 block just before your content.

WordPress “Page” Templates

I think that a WordPress “Page” is the most mis-understood thing in the entire blogging software. When you go to “Write” in the WordPress dashboard you have options to write a “Post” or a “Page”. The choice to write one or the other is a choice basically to use the “blogging paradigm” or not. By writing a “post” you are writing not only a “single” page post, but it also will be listed on the home (blog) page, and archive page, as well as category and post pages. The choice to author a “page” is like an “about page” – it’s static in the sense that it won’t be listed on blog type pages. It will only be listed in the navigation of your theme or a list of “pages” in the sidebar.

Pages can be anything, an about page, an advertise with us page, a contact page, or even a series page where you provide descriptions of posts and link to them on one central location. Pages are a great way to organize content in your blog, and the more you create – the more you’ll find the need to create custom layouts. On this blog I created a page template with a custom sidebar for my forum. I also created a special one for my archived posts sitemap, and testimonials. On one of my other blogs I created one with no sidebar at all for my find cheapest gas page.

If you want to create a custom template theme file for that you can assign to any “page” that you write in WordPress all you need to do is open your index.php file and “save as” whatever name you want (like sitemap-template.php or whatever). I try to name all mine something-template.php, just to keep them straight.

In the top of that page you are going to need to add the following code (copy and paste) so it gets identified as a template in WordPress:

Change “My Template Page” to whatever you’re naming your template, and then customize the page by creating a master archive index template, create a custom 404 error page template, or even create templates with alternate sidebar layouts.

In your WordPress dashboard to assign a template, just scroll down past the post text box and under “template”, just find your custom template in the drop down and choose it to apply that particular template to your page and “save”!

The possibilities are endles…

Creating a Custom WordPress Search Page

In WordPress when someone searches your content, “search.php” is used for the results. You could create a custom search results template so people find what they need each and every time. You could also monetize this page with an ad if you wished, or just provide links to your top content on top of the search results. If your theme doesn’t have a search.php, just create one based on index.php.

Creating a Custom 404 Error Page in WordPress

I think that one of the most important things is not just what people see when they find your content, it’s what they see what they don’t find anything at all. If someone gets a “404 page not found” error on your WordPress blog, WordPress looks for the “404.php” file first, and if you don’t have one it uses index.php by default. If you don’t have one, create it based on your index.php file – and then customize it right away! Most themes just have some bogus default message like “error – not found”.

The first thing you want ot do is to erase that and put a nicer message. Write a paragraph and include some links to your top areas AND your contact form in case they want to get ahold of you. Next, install a plugin that gives them automatically the best results it can – for details read WordPress Hack #4: Create a Custom Error 404 Page.

Wrapping it Up…

No matter where you got your WordPress theme, and whether it was basic or a Premium one you paid top dollar for – it CAN and SHOULD be customized to it’s fullest possible extent. A theme designer often is worried about the web design and layout aspect ONLY with no consideration for organization of your blog, it’s content, SEO and search indexing capabilities – let alone error messages or search pages. Do your self (and your visitors) a favor and make sure that you have ALL areas of your WordPress template hierarchy covered!

I hope I didn’t give you too much work to do, but by the time you’re done with everything I just taught you you will have a much better understanding of how WordPress and WordPress Themes work. When you’re done you might be interested in moving on an reading How to Create Your Own WordPress Theme