Understanding the WordPress Template Hierarchy

Quick Introduction – I’m Sarah and I will be writing each Sunday on intermediate to advanced WordPress topics including template development, tips and tricks, PHP coding for use in WordPress and plugin development. I’ll be basing my posts on the latest version of WordPress, and also assume an understanding of HTML and CSS, and presume you don’t run at the sight of a little PHP I’d love to hear what you want to read about on this subject so please let me know in the comments.

Understanding the WordPress Template Hierarchy

At the very least a WordPress theme requires just two files, style.css and index.php. Everything on your site can run off just these two files. However, having just two files would create the same look throughout the site on every page. Whilst you could use some conditional tags in your index file to control what is displayed on different sections of the site, this would create a larger and more complicated file to deal with, especially if you decide to change things in, say, 6 months time. So to keep things easier to read you can work with several files to keep things organised, allowing you to control different aspects of each section easily.

WordPress runs off a Template Hierarchy, which means it will look for a particular file for the current page viewed, in the active theme directory and if it cannot find that file it will then look for the next filename in the hierarchy and so on until it finds a match. Understanding this hierarchy can help with creating your own template and also modifying one of the many free templates available online.

So we have the several sections of a WordPress site including Front Page, Categories, Archives, Single Post and Static Pages. The Front Page is best kept as index.php (home.php could be used however this is no longer necessary since WordPress 2.1). The hierarchy of the other sections are:

Categories

1. category-ID.php Where ID is the selected category’s ID
2. category.php
3. archive.php
4. index.php

Archives

1. date.php
2. archive.php
3. index.php

Single post

1. single.php
2. index.php

Static Page

1. Specified Page Template
2. page.php
3. index.php

Tag Page

1. tag-tagname.php Where tagname is the selected Tag’s slug
2. tag.php
3. archive.php
4. index.php

Author Page

1. author.php
2. archive.php
3. index.php

Search Results

1. Search.php
2. index.php

404 Page

1. 404.php
2. index.php

This means that if you view a specific category e.g. ‘Design’ with an ID of 3, WordPress will first look in your template directory for the category-3.php file, if it doesn’t find that it then looks for category.php, if that doesn’t exist it will look for archive.php and finally it will use index.php as a template for laying out the page.

If you intend to have two or more of these additional section files eg. index.php and archive.php, then it’s more efficient to separate your general header and footer into their own files, and the sidebar/menu into its own file if it cannot fit into the header or footer, or if it is not going to be on every page (like the way the default theme Kubrick works).

You may wonder why the need for the various files (or maybe not!). This hierarchy gives the option to have a different structure for different sections, for example excerpts of posts displayed on the front page, category and archive pages, the full post on the single page with a comments form, and the full content on a static page, without the comments form and category details (as pages are not put in categories). Alternatively you may want a different structure for your category and archive pages, compared to your front page.

Hopefully this has explained the template hierarchy, giving a basic understanding of how the file system works. Understanding the basic concept of this means we can start to look at developing your own theme from scratch in the forthcoming posts.

Written by Sarah from Stuff By Sarah
Posted on April 13th, 2008 and filed under WordPress Coding & Design
Do not forget to subscribe to our RSS feed for updates

6