A beginner’s guide to WordPress template hierarchy

WordPress template hierarchy is an essential concept that every developer needs to learn to start operating on this CMS platform.

This structure guides each page’s rendering, making the information load much more dynamic, agile and free of errors and failures. It is important to understand how this structure works to make changes to a site.

WordPress’s standards for page layout are also essential to keep its construction properly organized.

This structure impacts how to make changes on websites, turning the work easier for developers. Consequently, page customizations on a website can be complete and able to reach maximum potential.

This content will show you more about how the WordPress template hierarchy works, its importance, and the categories that follow this structure on a website. We will cover the following topics:

• WordPress template hierarchy
• Categories has a built-in WordPress template hierarchy
• Template hierarchy in code

Keep reading to learn more about the subject!

WordPress template hierarchy

WordPress template hierarchy is the template structure that every website operated on this CMS platform follows.

Each theme used must have its parts and details following this arrangement, ensuring two main issues: a standardized reading by WordPress and a much easier alteration process in the developers’ work.

Another important question is the page rendering done by browsers. This work happens from the HTML file offered by WordPress, which makes reading much faster and easier with the template hierarchy.

Essential when using and creating themes

Template developers have placed many theme options on the market, which is very positive for platform users.

For this reason, it is essential to standardize the structure of every page, which helps to establish a perfect interaction system between WordPress and the theme used. This way, it is possible to avoid different constructions that could make the work more challenging.

In WordPress, PHP is used to develop pages and, consequently, themes. When creating a new theme, developers need to follow the template hierarchy to maintain a standard, restricting possible complex constructions that would difficult file reading.

This standardizing also avoid slowness in pages and potential incompatibilities with plugins, for example.

Ease to edit themes

WordPress template hierarchy is also critical to make easy any modification in a theme. With a structure that always repeats itself, choose a category within the various possible ones and perform the necessary adjustments.

Besides being agile, this process is assertive and can be repeated several times without generating doubts or complications.

To better illustrate the WordPress template hierarchy, website WPShout designed the following layout:

Categories has a built-in WordPress template hierarchy

WordPress websites are composed of seven different types of pages: Site front page, Single posts, Single pages, Category and tag pages, Custom post types, search results pages and 404 error pages.

On each of these pages, there is a built-in WordPress template hierarchy, which we will into detail below!

Site front page

WordPress loads a website’s home page first. To do this, the platform will search the file “front-page.php”, and if it is not found, the option will be “home.php” and finally “index.php”.

The front page hierarchy develops exactly in this order, without any variation of this cycle of tasks performed by WordPress.

The files will often have exactly the same content, but the platform still follows its functioning with this workflow.

This is what will ensure a standardized operation, keeping the hierarchy the right way. Front page site, as you can see, has one of the simplest schemes in a website.

Single posts

Single post is a category that aggregates each of the contents published in the platform. To show a post to the user, WordPress will render a template of this type of page, for this, the task to be executed will load the following hierarchy of PHP files, in the following order:

• single{post-type}-{slug}.php;
• single{post-type}.php;
• single.php;
• singular.php;
• index.php.

The first two types of files will allow you to load a custom post, with changes to its structure. However, if this is not the particular post situation, the loading will be of the default format, “single.php”.

WordPress will keep searching until it reaches index.php, if necessary since it is a file that will always be available.

Single pages

As the name suggests, it is any page within the website. When the user accesses, for example, an item in the menu bar, WordPress directs them to a new single page.

Therefore, the rendering of these pages needs to follow a very clear hierarchy, which in this case, will be:

1. Custom template file;
2. page–{slug}.php;
3. page-{id}.php;
4. page.php;
5. singular.php;
6. index.php.

One of the main differences in the hierarchy of this type of page is the first item. It is not a PHP file because WordPress works to recognize any content as a single page.

If this is the case, the platform can load and render normally. If not, it keeps looking for other files that can help create the HTML of the page.

Category and tag pages

Categories and tags play basically the same role when aggregating content within WordPress, which makes it easier to upload. In category, the hierarchy will work like this:

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

Tags also follow a very similar hierarchy:

1. tag–{slug}.php;
2. tag-{id}.php;
3. tag;
4. archive.php;
5. index.php.

Custom post types

It may be necessary to post varied contents that are not identified as a standard type of platform post. They have modified structures to receive some customization and, for this reason, WordPress will also need to load the hierarchy used.

1. arquivo-{post_type}.php;
2. archive.php;
3. index.php.

Because it is a different type of post, hierarchy is simpler and more objective, different from most types of pages shown so far. Still, its operation is the best that WordPress needs in terms of loading.

Search results pages

Search results pages are one of the simplest templates you’ll find in WordPress, and this is shown in its hierarchy, which is much shorter than usual:

• search.php;
• index.php.

404 error pages

The same happens on the 404 error pages:

1. 404.php;
2. index.php.

Template hierarchy in code

WordPress requests, as you saw, go through the file “index.php”. This file generates the following lines of code:

define('WP_USE_THEMES', true);

/** Loads the WordPress Environment and Template */
require( dirname( __FILE__ ) . '/wp-blog-header.php' );

wp-blog-header.php and wp-blog-header.php contains:

if ( !isset($wp_did_header) ) {

    $wp_did_header = true;

    require_once( dirname(__FILE__) . '/wp-load.php' );

    wp();

    require_once( ABSPATH . WPINC . '/template-loader.php' );

}

require_once( ABSPATH . WPINC . ‘/template-loader.php’ ); contains the theme hierarchy to show the page. The main lines of the code in question bring:

if ( defined('WP_USE_THEMES') && WP_USE_THEMES ) :
    $template = false;
    if     ( is_404()            && $template = get_404_template()            ) :
    elseif ( is_search()         && $template = get_search_template()         ) :
    elseif ( is_front_page()     && $template = get_front_page_template()     ) :
    elseif ( is_home()           && $template = get_home_template()           ) :
    elseif ( is_post_type_archive() && $template = get_post_type_archive_template() ) :
    elseif ( is_tax()            && $template = get_taxonomy_template()       ) :
    elseif ( is_attachment()     && $template = get_attachment_template()     ) :
        remove_filter('the_content', 'prepend_attachment');
    elseif ( is_single()         && $template = get_single_template()         ) :
    elseif ( is_page()           && $template = get_page_template()           ) :
    elseif ( is_singular()       && $template = get_singular_template()       ) :
    elseif ( is_category()       && $template = get_category_template()       ) :
    elseif ( is_tag()            && $template = get_tag_template()            ) :
    elseif ( is_author()         && $template = get_author_template()         ) :
    elseif ( is_date()           && $template = get_date_template()           ) :
    elseif ( is_archive()        && $template = get_archive_template()        ) :
    elseif ( is_comments_popup() && $template = get_comments_popup_template() ) :
    elseif ( is_paged()          && $template = get_paged_template()          ) :
    else :
        $template = get_index_template();
    endif;
    /**
     * Filter the path of the current template before including it.
     *
     * @since 3.0.0
     *
     * @param string $template The path of the template to include.
     */
    if ( $template = apply_filters( 'template_include', $template ) )
        include( $template );
    return;
endif;

Understanding WordPress template hierarchy is essential for developers to know how to work more accurately and quickly to make editions, adjustments and customizations on websites.

Page types have well-defined structures and the loading of files works in pre-defined flows, which makes the whole process flawless.

WordPress is one of the main platforms to create high-quality corporate blogs. So check out our guide on how to create and manage yours!