So... you’d like to create your own WordPress Website and prefer to create your own custom templates. That’s great! Considering it is fairly easy to generate a template from scratch within WordPress.

But not so fast now. Before we jump into it, you should first understand how the WordPress Template Hierarchy works. This will help you in deciding which templates you should and should not create.

WordPress is smart when it comes to templates. If you use the correct naming convention for your template-files, WordPress will automatically recognise them and apply them accordingly. Use this to your advantage and you or your client will never need to worry about selecting a template for a post or page. If done correctly, WordPress will do all the magic for you.

How does it work?

To quote WordPress:

“Template files are modular, reusable files, used to generate the web pages on your WordPress site. Some template files (such as the header and footer template) are used on all of your site’s pages, while others are used only under specific conditions.”

There are 2 types of templates in WordPress:

1. templates within the hierarchy (automatically applied to page/post)
2. custom templates that live outside of the hierarchy (manually applied to page/post)

For the first type of templates, WordPress will try to match the query string from your URL with a template file. If there is no match, WP will automatically select the next default template from the hierarchy. This process will go on until there’s a match.

In case you are working with a child-theme, you will first need to check which templates the parent-theme is using. You might not want to overwrite a parent-template, if it also affects posts or pages that don’t need a new template. WP will always alternate searching the child-theme’s highest hierarchy template followed by the parent-theme’s template.

However, if you selected a custom template for your page/post instead of the default, WordPress will skip the whole hierarchy and go directly to the custom template file.

The hierarchy

Within the hierarchy there are different types of templates. Here are some of the most commonly used:

• the home page
• the blog posts index page
• the privacy policy page
• the single posts pages
• the single (static) pages
• the category index pages
• the tag index pages
• custom taxonomy index pages
• custom post types index pages
• 404 page

If WP fails to find any of the above templates, it will revert to fallback templates like:

• archive.php
• index.php

Home.php is not your Homepage. Or… is it?

It’s very important that you understand that there’s a different hierarchy for the front page and the blog posts index page of your website.

WordPress was initially created as a platform for bloggers. This means that your blog-page is in fact your homepage. In other words home.php serves as the template for the blog posts index, whether it is being used as the front page or a separate static page.

While this might make perfect sense in the earlier days of WordPress, this is confusing for the WordPress development of today.

Let’s make it a bit more confusing. 

If WP detects the front-page.php template, this will overwrite the home.php template. You can use this template to create your own custom home page. However (this is where it gets confusing), you can also choose to set this template to display your blog posts index.

So unless you want your home page to display your blog posts, you should always put the Reading Settings in WordPress like this:

This way, WordPress will automatically use the front-page.php template as your home page. If you also have a home.php file, the “Posts index page’ will in this case be rendered with the home.php template.

Just remember that, if you change the settings to “your latest posts”, WordPress will want to use front-page.php to display your blog posts index. Meaning this approach still has some issues that need to be fixed.

One way to solve this, is to avoid using the home.php template and add some conditional statements to your front-page.php and index.php templates. 

Settings set to “Your latest posts”

To determine whether your home page should display the blog posts index or a custom static page, you can add a conditional statement that either loads the template for your static home page or the template for the blog posts index.

<?php if ( is_home() ) : ?>
//<!--    If your homepage display settings are set to "Your latest posts', display this template -->
  <?php get_template_part( 'template-parts/content', 'blog' ); ?>

<?php else : ?>

<!--    If your homepage display settings are set to "static page", display this template -->
  <?php get_template_part( 'template-parts/content', 'home' ); ?>

<?php endif; ?>

Settings set to “A static page”

If home.php doesn’t exist and you selected “A static page” in your Reading settings, WP will now use the index.php template for your blog posts index. This means you will also need to add a conditional statement to your index.php template that loads the blog template when you’re displaying the blog page.

<?php if ( is_home() && ! is_front_page() ) : ?>
<!--    If your homepage display settings are set to "Static page', use this template for your blog index page -->
  <?php get_template_part( 'template-parts/content', 'blog' ); ?>

<?php else : ?>

<!--    If a certain template file is missing in the hierarchy, use this template -->
  <?php get_template_part( 'template-parts/content', 'none' ); ?>

<?php endif; ?>

Here’s a diagram with the complete hierarchy:

Category and Taxonomies

While taxonomies are custom categories, WordPress does treat them differently in the hierarchy.

For Categories, WP will first look for a template that starts with the name category and then check if there’s a template for a specific category. This can be either the category slug (recommended) or the id.

The fallback templates are as follows:

1. category-{slug}.php
2. category-{id}.php
3. category.php
4. archive.php
5. index.php

For taxonomies, you will first need to indicate the name of your custom taxonomy. The fallback templates are:

1. taxonomy-{taxonomy}-{term}.php
   *if you compare this with category, taxonomy stands for your “custom category name” and term for the custom “slug”
2. taxonomy-{taxonomy}.php
3. taxonomy.php
4. archive.php
5. index.php

Other templates

The hierarchy for other post-types works in the same way. WordPress will first look for the most specified template, followed by the next most specified template, until there’s only the index.php template page.

Conclusion

Combined with conditional statements, you can use the hierarchy to your advantage and keep your template structure clean and consistent. The more templates you create, the more complex and difficult your website will be to maintain. If used wisely, you can keep the template-count to a minimum. A rule of thumb you could use is:

If 2 or more pages/posts have the same layout, try to make use of the same template. It’s always better to change one of the page’s layout afterwards, by adding a more specific template, than to correct one and the same layout on several templates. 

Needless to say,  how you use the template hierarchy is totally up to you. 

Sources

• https://developer.WordPress.org/themes/basics/template-hierarchy/
• https://wphierarchy.com/