WordPress Tip: Template files and naming conventions

Ed: This article is part of the 21 Days of WordPress Tips

The WordPress template files can often be confusing. Figuring out which files get used and when, which ones you don’t need, etc is very daunting. Not to mention, this information is pretty hard to sift through in the WordPress codex.

In this post article I’ll give you a few of my favorite tips when it comes to piecing together the WordPress template files to meet your needs.

753px-template_hierarchyThe Hierarchy

Click the picture on the right to get a look at how the WordPress template hierarchy works. Learning this is a must in developing your own themes.

First off, index.php is the root of everything. You can actually run an entire theme off an index.php and style.css. And if you are missing a template file that is needed, index.php will be defaulted to.

Another heavily used file is archive.php. If you open this file from the “default” theme that downloads with WordPress, you’ll see code that’s used to show all the categories, dates, authors, etc archives.

Bookmark this image and refer back to it any time you get stuck on which template file will be called and when.

Powerful Categories

One of the more powerful template files that I rarely see used is the category-[id].php. The image above is somewhat misleading as the file will never actually be named category-id.php. The ‘id’ part of the filename is replaced with the numeric id for the category you would like to show. i.e. category-1.php or category-28.php to correspond to categories id 1 and 28.

Using these template files can be very useful if you would like to show an entire category of your site in a custom layout.

I use this technique on the SmallBizTrends.com website. I have a default category.php file that shows for any category on the site (here’s an example), however there is a special category that is sponsored by HP that needed to display different elements. I used a category-[id].php template file to split out that section and show those posts differently (click here to see it).

Page Template Filenames

As we’ve seen in earlier WordPress tips, you can create custom page templates that override the default page.php template. Again, the above image is a bit misleading as the file doesn’t have to be named pagename.php. In fact, it can be named whatever you like, however I recommend a very specific naming convention.

When you create a page template it is either for a specific page on your site (i.e. Home Page, About, etc) or a specific layout (i.e. one column, two column, etc). My advice is to include the descriptions in the name of the file:

  • page-home.php
  • page-about.php
  • page-one-column.php

By following this convention, you and anybody else that works on the site in the future will know what those template files do. I’ve seen page template files named all kinds of random things and it’s always hard to sift through exactly what files you need. Follow the above naming convention to save yourself and any future developers a huge headache.

A useful 404

It’s easy to get caught up in creating your WordPress theme and your content and forget that this very useful template file exists. The 404.php gets called when a page is called that doesn’t exist. Whether it’s a broken link or a user typing something wrong, odds are good that somebody is going to a request a page of your site that doesn’t exist. Instead showing a useless 404 error, use this opportunity to point them to other portions of your website.

You can see ours here


That’s my favorite tips on how to correctly use your template files. You have one or two of your own?

Tim Grahl
Tim Grahl
Tim Grahl is the author of Your First 1000 Copies and the founder of BookLaunch.com. He has worked with authors for a decade to help them build their platform, connect with readers, and sell more books. He has worked 1-on-1 with over a hundred authors including Daniel Pink, Hugh Howey, Barbara Corcoran, Chip and Dan Heath, Sally Hogshead and many others. He has also launched dozens of New York Times, Wall Street Journal, and Washington Post bestsellers.