Wordpress - Template Hierarchy: confused with index.php, front-page.php, home.php
Front page logic is one of the most confusing features in WordPress and is exceptionally hard to explain and summarize. As mentioned in comment while back I burnt unholy amount of time to put together my front page logic cheat sheet for it.
But since this is a popular thread let me try to answer those very specific questions you had.
What's the difference between the
home.php
andindex.php
?
home.php
is template for posts index (archive of native Post post type, which is a special case in WP). WP will attempt to look it up for index of posts, whether they are displayed at the root of the site or at dedicated posts page.
index.php
is catch–all template. It is final choices in all branches of template hierarchy and will be picked when nothing else fits, for both archives and singular views.
Only posts index can use home.php
, but all other contexts might and will use index.php
.
What's the ideal condition to use a
home.php
than anindex.php
You use home.php
to customize posts index.
You use index.php
to provide the most generic template in your theme, suitable for display of anything.
Some themes choose to have empty index.php
and ensure they have more specific templates for all possible cases, so it never has to be used.
What's the ideal condition to use a
front-page.php
?
front-page.php
is used for posts index at the root or static front page, if enabled.
It is a high priority template, so if theme has it you cannot select arbitrary template for static front page. For this reason it is almost never included in publicly released themes (which is correct).
The best use for it is in private projects, since it's easier to configure than page template.
When I'm using a
front-page.php
then what specific task anindex.php
is doing for me then?
index.php
is still a catch all template for all other cases.
If you use static front page (to which front-page.php
will apply) then your posts page will try to use home.php
and then index.php
.
The front-page.php
file is the site front page template. It will always be used on your site front page, regardless of whether get_option( 'show_on_front' )
is set to page
or posts
.
The home.php
template file is the blog posts index template. It will always be used to display your blog posts index, regardless of whether the blog posts index is displayed on the site front page, or on a different page.
In the case that both front-page.php
and home.hpp
exist, and the get_option( 'show_on_front' )
is set to posts
(i.e., the site front page displays the blog posts index), the front-page.php
file will take precedence over the home.php
file.
The index.php
file is the default fallback template for all contexts in the Template Hierarchy. It is only ever used if a more-specific template file does not exist for the current context.
The template hierarchy for the site front page is:
front-page.php
- If
'page' == get_option( 'show_on_front' )
: page hierarchy - If
'posts' == get_option( 'show_on_front' )
: blog posts index hierarchy
The template hierarchy for the blog posts index is:
home.php
index.php
The template hierarchy for pages is:
- Custom page template
page-{slug}.php
page-{id}.php
page.php
index.php
All this comes from a thorough reading of the Template Hierarchy.
home.php
is used if:
- Your site's front page is set to display a list of posts, or
- A static front page is set, and
- A visitor goes to the page that you've defined as your "list of posts" (eg,
http://example.com/blog/
)
- And the theme has a
home.php
file
If the last condition isn't met -- ie, there is no home.php
file in the theme -- then index.php
will be loaded.
front-page.php
will be used if:
- A static front page is set, and
- A visitor goes to the page that you've defined as your "static home page" (ie,
http://example.com/
), and - The theme has a
front-page.php
file
If the last condition isn't met -- ie, there is no front-page.php
file in the theme -- then index.php
will be loaded.
In summary
If you want to customize your list of posts, use home.php
.
If you want to customize your static home page, use front-page.php
.