Beginner’s Guide to WordPress Template Hierarchy Lifetime

WordPress Template Hierarchy : On WordPress, templates are the PHP files that make up a theme. They form the HTML structure of the different pages of the site. Knowing how they work, their hierarchy and their nomenclature is essential to create your own WordPress theme or to easily modify an existing theme.


A theme is a set of files located in the / wp-content / themes / timename directory . These files are of different types: PHP (templates), CSS (style sheets), JS (scripts), JPG / PNG / GIF (images), PO / MO (translations) to name only the most frequent ones.

You can install several themes on your site, simply copy them into the / wp-content / themes directory or install them directly via the back office. You can view the installed themes and activate one in the “Appearance> Themes” menu.

Each theme is different, so you will never find exactly the same files from one theme to another. Some will have very few, others may have hundreds, divided into several subfolders.

However, two essential files will always be present regardless of the theme: style.css and index.php .

WordPress Template Hierarchy

WordPress Template Hierarchy

WordPress Template Hierarchy

WordPress Template Hierarchy

WordPress Template Hierarchy

WordPress Template Hierarchy

WordPress Template Hierarchy


This is the main style sheet of the theme, in which the CSS rules are located. Beyond its formatting role, this file is essential because it contains the metadata of the theme, which allows it to be correctly interpreted by WordPress and appear in the back office.

Here is an example of metadata that can be found at the top of the style.css file , inserted into a comment:

Theme Name: Techy Videos
Theme URI: https://www.techyvideos.com
Description: Real Tech Videos
Version: 3.0
Author: Sam Rocksiz

Some themes use this file only for metadata and place their CSS rules elsewhere (often in a “css” subdirectory).


This is the default template for the theme. This is where the basic HTML structure of the site is located, as well as the “WordPress loop” that will retrieve the content present in the database to display it dynamically on the pages. If the file index.php is the only template of the theme, all pages of the site will use it. However, it is extremely rare to find a theme based solely on this template, although this is possible thanks to the conditions of WordPress (called ” conditional tags “).


On a WordPress site, we find different types of pages that all require a particular display and therefore a different HTML structure:

  • Home page
  • “Static” page
  • article
  • Category of articles (list of articles by thematic)
  • Articles archive by date
  • Articles archive by author
  • search results
  • Media (photo, video …)
  • 404 Error Page
  • Tag page (list of articles with the same tag, or label in French)
  • Custom post (custom item type, which works differently than traditional items)
  • Custom post archive
  • Custom taxonomy (similar to categories and tags but for customs posts)
  • Specific “static” page not respecting the standard model

This list could be further expanded but these are the most common scenarios.

Rather than using a large number of conditions in the index.php file to modify the structure of the page according to the type of content, WordPress allows the use of templates specific to each type of page, which will be used in priority over at index.php (example: single.php for an article, page.php for a static page, 404.php for the 404 error page, etc.).

WordPress Template Hierarchy

Templates on WordPress respond to a precise hierarchy based on their nomenclature. Here is the hierarchical scheme proposed by the WordPress codex (official online documentation), which must always be kept in mind when designing a theme:

WordPress Template Hierarchy 1024x1017 - Beginner's Guide to WordPress Template Hierarchy Lifetime
Click to enlarge Image


This first case is very simple. In case of error 404 (page not found), WordPress will look in the theme a file named 404.php . This is a template that is not usually associated with any content in the database. The message displayed is in this case written in hard in the file. On some complex topics, it is possible to have a field provided for the 404 error message in the back office, that this template will then recover in the database to display it dynamically.

If WordPress can not find a 404.php file , it will use the default template index.php .


During an internal search, WordPress returns a results page that can contain articles and / or pages according to the setting defined by the user. To display these results, WordPress will use the template search.php in the theme, which contains a loop generally similar to the one used on archives and taxonomies (category, tag …). If it does not find search.php , it will use index.php .


This is certainly the most complex branch of the template hierarchy on WordPress. Before entering into the details, we must understand the concept of archive: it is a list of articles or “custom posts” (articles personalized) meeting certain conditions. The so-called “static” pages (simply called “pages” in the back office) are not listed in the archives. The default template for archives is archive.php .

The number of articles displayed on an archive page is defined in the back office in “Settings> Reading”. By default, 10 articles are displayed per page. This means that if 25 items are found by the archive loop, it will display 10 on the page, and a pagination will show the other 15 on the next two pages (10 on page 2, 5 on page 3).

WordPress Template Hierarchy

WordPress Template Hierarchy

WordPress Template Hierarchy

WordPress Template Hierarchy

WordPress Template Hierarchy

WordPress Template Hierarchy

WordPress Template Hierarchy

WordPress Template Hierarchy

WordPress Template Hierarchy

WordPress Template Hierarchy

WordPress Template Hierarchy

There are several types of archives, each with its own template: category, tag, date, author, taxonomy, custom post archive. If WordPress does not find the specific template of the archive in the theme, it will use archive.php which is the generic archive template. If this file is not present either, it will use index.php , or paged.php if it exists and the page to display is not the first page of the archive (ie page 2 or more) .

Here are the different archive templates that can be used on WordPress:


This template is displayed by WordPress on the categories of articles. The loop retrieves all items in the same category.

It is possible to use a specific template for a particular category to differentiate it from others. Just add the numeric identifier or the slug (standardized name in lowercase and without spaces, used mainly in URLs) to the filename, like this: category- $ id .php or category- $ slug .php .

Example for a category “News” whose numerical identifier would be “4” and slug “news”: category-4.php or category-actu.php .

If these two templates exist in the theme, WordPress will first use the one containing the slug. It is recommended to use instead the numerical identifier which is not likely to change, because a category can be renamed and its slug can be modified.

Tip: To find out the numeric identifier of a category, go to “Articles> Categories” and click on the category in question. The identifier is in the URL displayed by the browser: /wp-admin/edit-tags.php?action=edit&taxonomy=category& tag_ID = 13 & post_type = post

Here, the category identifier is 13.


Same principle as category.php but applied to tags, or “labels” on the French version of WordPress.

The custom template method based on the ID or tag slug also works: tag- $ id .php and tag- $ slug .php . The priority is given to the slug with respect to the ID. The trick to find the ID of a tag is the same as the one explained above for a category.


WordPress uses the date.php template for the article archive by date, whether by year, month or day (example: all articles of June 2015).


Same principle as date.php but for archives by author (all articles written by the same user). We often use author.php to display a short description of the author in addition to the list of his articles.

It is possible to differentiate an author page from the others by using author- $ id .php or author- $ nicename .php . Unlike categories and tags, the ID of an author can not be found easily, it must be searched in the database. It is therefore better to use the nicename, which can not normally be modified via the back office: it is the login ID of the user. The template based on the nicename will take precedence over the one based on the ID if both are present in the theme.


This template works like category.php and tag.php but includes custom articles, or “custom posts”.

A taxonomy is a way of sorting posts. Category and tag systems are the two standard WordPress taxonomies for sorting classic items. The difference between the two is that the category includes a hierarchical notion, with parents and children, unlike tags that are all of the same level.

For each type of custom post, we can create taxonomies, hierarchical or not. The “terms” associated with a custom post in a taxonomy are the equivalent of the categories or tags associated with an article. For example, on an artist’s site, for a custom post type called “works”, we could have a taxonomy “type of work” whose terms would be “painting”, “sculpture” and “engraving”.

Here is a complete article on the subject, to better understand the notion of taxonomy and term: http://boiteaweb.fr/taxonomies-termes-tutoriel-ultime-8152.html

To customize a particular taxonomy, use the taxonomy- $ taxonomy .php nomenclature , which will take precedence over taxonomy.php , generic taxonomy template. The variable $ taxonomy corresponds to the slug of the taxonomy. You can also customize a term using taxonomy- $ taxonomy – $ term .php , where $ term must be replaced by the term slug. Digital IDs do not work for these files, only slugs are accepted.


We have seen that it is possible to group articles by date or author thanks to the templates date.php and author.php . Similarly, it is possible to create a custom archive template for a custom post type, using the following nomenclature: archive- $ posttype .php where $ posttype is the slug of the custom article type.


These templates are used to display single posts, ie articles, pages and custom posts. They only post one post at a time, unlike archives.

More about the difference between an article and a page on WordPress: http://wpmarmite.com/difference-article-page-wordpress/


This is the standard template used by WordPress to display static pages. It is possible to create a custom page template that will take precedence on page.php . For this, there are two methods:

  • For a particular page, you can use page- $ id .php or page- $ slug .php . The use of ID / slug is the same as for the category.php and tag.php templates . You can find the ID of a page by looking in the browser URL on the edit page in the back office.
  • To customize multiple pages on the same template, it is best to use a specific page template. This is the only template file that can be named as you want, as long as you do not use an already existing file name in the template hierarchy. In order for the template to be detected by WordPress, just add this piece of code at the top of the file, which we will call here page-personnalizee.php (be careful to respect this exact syntax, especially in terms of spaces, otherwise the template will not work) :
Template Name: Page personnalisée

You must then select the page template in the back office on the interface for editing the page, in the “Model” drop-down list.

If none of these templates are found in the theme, the page will be displayed with the template index.php .


The template single.php is used by WordPress to display articles, media and custom posts. This is the default template for all posts that are not pages (the latter use page.php ).

There are three priority templates on single.php , to use or not according to the complexity of the site:

  • single-post.php : this template is only used to display standard WordPress articles (blog posts)
  • single- $ posttype .php : the equivalent of single-post.php for custom posts, where $ posttype is to be replaced by the slug of the custom article type (custom post type)
  • attachment.php : used to display the media (images, videos …). You can customize the display of certain media types by using three priority BOMs on attachment.php : $ mimetype .php , $ subtype .php, and $ mimetype _ $ subtype .php (in order of precedence). The variables $ mimetype and $ subtype correspond to the type and subtype of media, according to the standard “Internet media type” ( more info and list of types and subtypes )
    Example: the template video-mp4.php (type = video, subtype = mp4) will be loaded for all videos in MP4 format.

If none of these templates are found in the theme, the post will be displayed with the template index.php .


This page is special because its behavior and the template used will depend directly on the configuration of WordPress.

By default, the home page of a WordPress site displays all articles on the site, starting with the most recent. In this case, the template used will be home.php if it is present in the theme, or index.php otherwise. Many themes use index.php to display the home page.

On the other hand, if the homepage is a static page (configurable in “Settings> Reading”), the template used will be that of the page chosen for the reception. So it will normally be page.php , or a custom template if the page has one.

There is also a priority template on all others for the home page, which will be displayed regardless of the configuration chosen in the WordPress settings: it is front-page.php . It may be better to use it for the home page in the second case (static page) because it avoids creating a specific template and indicate it in the back office on the page in question.

Warning: if you want to create a specific page template for the home, do not call home.php as this could cause a conflict, this name is already used in the template hierarchy. Prefer a name of type home.php , or use page- $ id .php . The easiest thing is obviously the use of the front-page.php template which avoids creating a custom page template.

The comments-popup.php template is present in the template hierarchy but is actually very little used. It corresponds to a comments popup used with functions comments_popup_script()and comments_popup_link(), for themes that do not wish to display comments directly on the article or page.


On a site, some parts of the page are the same regardless of the page displayed. This is usually the header, the footer and the sidebar if it exists. Rather than duplicate these portions of code in all the templates of the theme ( index.php , category.php , single.php , page.php , etc.), we can use “template part” (PHP files similar to the classic templates ) that we will then include using the template tags. These are functions of WordPress that allow to insert information dynamically into a template. In this case, the principle is similar to the “include” PHP function that allows you to insert the contents of one file into another.


This file will contain all the header of the site: the opening of the tag <html>, the tag <head>grouping all the metadata of the page, but also the beginning of the tag <body>with fixed elements like the logo, the menu, links navigation, breadcrumb trail …

Simply call this file in a template (such as index.php ) with the function get_header()so that the complete code contained in header.php is displayed there. This avoids putting all the header information in each template.

If an element must change in the header on a particular page type, it is possible to use a conditional tag in the header.php file to test the type of page to perform an action (examples: logo not clickable on home page, menu color change for a certain category of items, etc.).

Its principle is similar to header.php but concerns the footer. It will usually contain the blocks at the bottom of the page (copyright, secondary navigation, links, call-to-action buttons …) and tag closures <body>and <html>open in the header. There are sometimes scripts.

The function get_footer()allows to call the contents of footer.php in a template (example: index.php ). It works in the same way as for get_header () .

As with the header, it is possible to use conditions in the footer.php file to display footer elements differently on certain types of pages.


Like the header and the footer, the sidebar is an area that can be called on all templates of the theme. Note that it is not necessarily placed on the side of the site, it can also be under the header or above the footer and take the entire width of the site. It’s only the CSS rules that will decide its visual location on the page. Some sites have no sidebar at all, it depends on the themes and the graphic and ergonomic choices of the webdesigner.

The content of the sidebar.php file is displayed in a template with the function get_sidebar(). If the sidebar should not appear on all the pages, we can insert this function only in the templates that correspond to the types of page where it should appear (example: category.php to show the sidebar only on the categories of articles) . It is not necessarily identical everywhere: it depends on the widgets that compose it (if it is a dynamic sidebar). Extensions like Restrict Widgets make it possible to condition the display of widgets according to the template, the category, the identifier of a page, etc.


In addition to the header.php , footer.php and sidebar.php files , there are other “template parts” that can be inserted into templates. Their use is not systematic. Here are some examples :

  • searchform.php : intended to display a form of search, file called with the functionget_search_form(), generally in the header or the sidebar (it is quite possible to use a “template part” in another)
  • comments.php : contains the comments area (submission form and comment list view), file called with the functioncomments_template(), usually in the article template ( single.php )
  • loop.php (or other similar name): contains the WordPress loop, function responsible for retrieving contents in the database (articles, pages) and displaying them, file called with the functionget_template_part(loop)

Note that the function get_template_part()allows you to call a custom “template part”. There is no predefined name for the loop template. The file loop.php could be named theloop.php , it would be enough to use get_template_part(theloop). It works with any name, as long as you do not use template names already defined in the template hierarchy (this would cause conflicts between files).


Some WordPress themes, including many premium themes, use a more complex template structure than that described in this article. It contains the basic files like index.php , single.php or even header.php , but these “classic” templates are often almost empty and consist of calls to other templates (the famous “template part”) located in subdirectories, in order to better structure the many pieces of code that make up these very complex themes.

As part of the creation of a “simple” WordPress theme, the use of the templates presented in this article will be enough to obtain a very complete and personalized website.

Codex WordPress: https://codex.wordpress.org/en/Model_file_helps
Interactive schema of the template hierarchy: http://wphierarchy.com/


Sam is a blogger and a freelancer working since 2013.

One Comment

  1. Hello there! I know this is kinda off topic but I was wondering which
    blog platform are you using for this site? I’m getting tired
    of WordPress because I’ve had problems with hackers and I’m looking
    at alternatives for another platform. I would be fantastic if you could point me in the direction of a good platform.

Leave a Reply

Your email address will not be published. Required fields are marked *

Back to top button