WordPress Template Hierarchy

Posted on January 29th, 2011

WordPress Templates fit together like the pieces of a puzzle to generate the web pages on your WordPress site. Some templates (the header and footer template files for example) are used on all the web pages, while others are used only under specific conditions.

WordPress uses the Query String— information contained within each link on your web site — to decide which template or set of templates will be used to display the page.

First, WordPress matches every Query String to query types — i.e. it decides what type of page (a search page, a category page, the home page etc.) is being requested.

Templates are then chosen — and web page content is generated — in the order suggested by the WordPress Template hierarchy, depending upon what templates are available in a particular WordPress Theme.

WordPress looks for template files with specific names in the current Theme’s directory and uses the first matching template file listed under the appropriate query section below.

With the exception of the basic index.php template file, Theme developers can choose whether they want to implement a particular template file or not. If WordPress cannot find a template file with a matching name, it skips down to the next file name in the hierarchy. If WordPress cannot find any matching template file, index.php (the Theme’s home page template file) will be used.

Please see the bellow image for the flow of Template hierarchy in wordpress. The Template Hierarchy In Detail

The following sections describe the order in which template files are being called by WordPress for each query type.

Home Page display

1.      home.php

2.      index.php

Single Post display

1.      single-{post_type}.php – If the post_type were videos, WordPress would look for single-videos.php. Note: not available until Version 3.0.

2.      single.php

3.      index.php

Page display

WordPress Pages:

1.      custom template – Where custom template is the Page Template assigned to the Page.

2.      page-{slug}.php – If the page slug is recent-news, WordPress will look to use page-recent-news.php

3.      page-{id}.php – If the page ID is 6, WordPress will look to use page-6.php

4.      page.php

5.      index.php

Front Page display

Note: this Front Page display feature is not available until Version 3.0.

1.      front-page.php – Used for both Your latest posts or A static page as set in the Front page displays section of Administration > Settings > Reading

2.      Page display rules – When Front page is set in the Front page displays section of Administration > Settings > Reading

3.      Home Page display rules – When Posts page is set in the Front page displays section of Administration > Settings > Reading

Category display

Category Templates:

1.      category-{slug}.php – If the category’s slug were news, WordPress would look for category-news.php

2.      category-{id}.php – If the category’s ID were 6, WordPress would look for category-6.php

3.      category.php

4.      archive.php

5.      index.php

Tag display

Tag Templates:

1.      tag-{slug}.php – If the tag’s slug were sometag, WordPress would look for tag-sometag.php

2.      tag-{id}.php – If the tag’s ID were 6, WordPress would look for tag-6.php

3.      tag.php

4.      archive.php

5.      index.php

Custom Taxonomies display

1.      taxonomy-{taxonomy}-{term}.php – If the taxonomy were sometax, and taxonomy’s slug were someterm WordPress would look for taxonomy-sometax-someterm.php

2.      taxonomy-{taxonomy}.php – If the taxonomy were sometax, WordPress would look for taxonomy-sometax.php

3.      taxonomy.php

4.      archive.php

5.      index.php

Author display

Author Templates:

1.      author-{nicename}.php – If the author’s nice name were rami, WordPress would look for author-rami.php. Note: not available until Version 3.0.

2.      author-{id}.php – If the author’s ID were 6, WordPress would look for author-6.php. Note: not available until Version 3.0.

3.      author.php

4.      archive.php

5.      index.php

Date display

Archive (Date) Templates:

1.      date.php

2.      archive.php

3.      index.php

Search Result display

Creating a Search Page:

1.      search.php

2.      index.php

404 (Not Found) display

Creating an Error 404 Page:

1.      404.php

2.      index.php

Attachment display

Attachment Templates:

1.      MIME_type.php – it can be any MIME type (image.php, video.php, audio.php, application.php or any other).

2.      attachment.php

3.      single.php

4.      index.php