What Most Web Designers Have Wrong About WordPress Theme Hierarchy

WordPress theme design can at first seem rather daunting; even for seasoned web designers. The simplest of themes seem to be made up of multiple files that are somehow interconnected.

But the good news is this: There is a logical system behind the confusion. If you’re willing to roll up your sleeves and learn a little PHP, you can turn your static HTML designs into dynamic WordPress websites.

You could of course use our services instead, but we like to give you a choice!

In this article I want to start by focusing on the key mistake that most would-be WordPress theme designers make when it comes to working with the WordPress theme template hierarchy, then go on to give you a broad overview of how WordPress themes should come together.

The Biggest Secret About WordPress Theme Development

Despite all the apparent complications with WordPress theme development, creating your own WordPress theme can be as simple as you want it to be.

What if I told you that you can create a simple WordPress theme with just two files?

Those two files are index.php and style.css. They ultimately won’t be all you want, but they are all you need.

If you have already created a static design with an index.html and style.css file, you can literally copy and paste the contents of each into a new index.php and style.css file, add a little extra information, zip the files up in a folder and upload it to WordPress. Hey presto — your first WordPress theme!

To prove my point, let’s do just that. We’ll start with our index.php file:

<!DOCTYPE HTML>
<html>
    <head>
        <meta charset="utf-8">
        <title>
            My First WordPress Theme
        </title>
    </head>
    <body>
        <p>Hello World!</p>
    </body>
</html>

As you can see, we’re using the same basic HTML as we would normally, with no PHP in sight. Theoretically speaking, PHP is optional when it comes to theme development, although you will certainly find the need for it if you want to design fully-fledged WordPress websites. Omitting PHP in your theme files essentially renders WordPress redundant.

In terms of your style.css file, it only needs one thing to work: a stylesheet header. This is made up of a few pieces of information that allow WordPress to identify your theme.

Here’s a simple example, which should be inserted as a comment in your style.css file:

/*

Theme Name: My First WordPress Theme
Author: My Name
Description: My first ever WordPress theme!
Version: 1.0

*/

There are many other header items that can be included in your stylesheet, but only a handful are mandatory. Here’s the complete list:

  • Theme Name.
  • Theme URI. If your theme has a homepage, this is where you add it.
  • Author. Don’t be shy!
  • Author URI. If you have a personal/portfolio website, you can link to it here.
  • Description.
  • Version.
  • Licence. Click here to learn more about WordPress them licensing.
  • Licence URI. It’s good practice to include a link back to the licence you choose for your theme.
  • Tags. These tags are used within WordPress.org to filter your theme down by specific characteristics (e.g. “one-column”, “custom-header”).
  • Text Domain. This is used for internationalization/translation purposes.

(Please note that your theme’s name must be unique. If you choose a name that already exists, you will create a conflict within WordPress.)

Save your index.php and style.css file into a folder and give it a unique name. Use hyphens instead of spaces. Once you’re done, zip the file.

Next, navigate to Appearance > Themes from your WordPress installation and click on the Add New button. From the resultant screen you can upload and activate your new theme.

Once you’ve done that, navigate to your homepage and you’ll see your first ever WordPress theme:

Your First WordPress Website

To confirm that this has been recognized as a theme within WordPress, just navigate back to Appearance > Themes. You will find your theme listed amongst any others you have installed on your site, and you can even click on it to reveal further details that you included in your stylesheet’s header:

WordPress Theme Details

Granted, your theme not much to write home about at this stage, but the above example demonstrates just how simple WordPress theme design can be.

It also reveals that big secret I mentioned above: index.php does not just represent your site’s homepage (although it can) — it is the basis for everything in WordPress theme design.

Getting to Know index.php And WordPress Theme Template Hierarchy

You would be forgiven for assuming that index.php is intended to be the homepage of your WordPress website. Well, it’s not. It’s far more important.

I said above that you can create a WordPress theme with only two files, one of which is index.php. Well, I meant that in every sense — not just in terms of creating a simple “Hello World!” example.

You see, WordPress’ theme template hierarchy works in such a way that if a more specific template file does not exist, it will default back to the next most ‘senior’ file. And guess what the most senior file is; what WordPress ultimately defaults to? That’s right: index.php.

To give you a better idea of what I mean, here’s a visual representation of the WordPress theme template hierarchy:

WordPress Theme Template Hierarchy

As you can see, there are a huge number of template files that can be used to build a WordPress theme — everything from a single blog post page (single-post.php) to a 404 error page (404.php). But the most important thing is this: if WordPress doesn’t find the most specific file, it defaults back to the next most senior file.

Ultimately that leads back to index.php: the Daddy of WordPress theme template files.

So index.php isn’t the homepage at all — ideally, WordPress would first seek out front-page.php, or subsequently home.php for that purpose. Index.php is a last resort.

Where Do You Go From Here?

We’ve only scratched the surface of WordPress theme development in this article, but now you should know that each template file in a WordPress theme relates to a particular type of page you would see on the front end. For example, a single blog post is most specifically represented by single-post.php, then single.php, then index.php.

WordPress will keep working backwards until it finds something to hang its hat on, but the more specific theme files give you an opportunity to create customized designs and layouts for the different pages on your site.

Once you understand that, you can start from a simple position (i.e. index.php) and flesh your design out from there. Like I said; you can create a WordPress theme with just two files, but in reality you’ll want to make the most of what WordPress has to offer and exploit its theme template hierarchy more fully.

If you want to explore the WordPress theme template hierarchy in more details, I recommend the following two resources:

Tom Ewer

Tom Ewer is a freelance blogger, longtime WordPress enthusiast and the founder of WordCandy. Find him at http://wordcandy.co
  • re: “WordPress theme design can at first seem rather daunting; even for seasoned web designers. The simplest of themes seem to be made up of multiple files that are somehow interconnected.”

    Well…that’s quite the mouthful, eh? Perhaps the wrong is on the wrong foot? If you know what I mean.

  • p.s. fwiw, this theme architecture aims to add some common sense standardization, as well as remove some friction from the broader WP theme dev process. Enjoy!

    But you have to be willing to reimagine the whole current muck of a process. If you want SOSDD then this might not be for you 🙂

    https://github.com/WPezBoilerStrap

    • Thanks for the resource Mark, is quite interesting and I didn’t knew it!

  • Theme development is very hard to explain in an way, that makes it easy to understand. And I’m still waiting to se the guide/tutorial that makes it simple.

  • You suggest important post for web designers. In my point of view, it is very useful post about wordpress. Thanks to share this great post with us.