A WordPress user can choose the type of content displayed on the homepage. A new WordPress site’s default behavior is to display a view of the website’s most recent posts. However, it is also possible to set a static page as the homepage.
Changing the default behavior to display a static page can be done by visiting Settings > Reading in the WordPress admin area. From there, the user can select published pages for the homepage and posts page. In this case, displaying a static page at the site root means the latest posts will appear on a separate dedicated static page.
As a theme developer, creating the best scenario for end users may seem complex, and it may be helpful to view things at a higher level.
The WordPress template hierarchy
As a theme developer, you will likely be familiar with the WordPress template hierarchy. If not, it’s a good idea to learn more about it. The template hierarchy is one of the most important things to understand when building a theme. The WordPress template hierarchy works, along with the active theme, to determine what template file will generate any given view of a WordPress site. Highly recommended is this tutorial on LearnWordPress.org, covering the basics of the WordPress template hierarchy.
The template hierarchy attempts to locate a template for the page a site visitor is viewing, looking for templates in order of specificity, and falling back to the generic index template if no other templates are found.
For sites with user-level templates created in the Site Editor, the hierarchy remains the same, except that the templates may not be drawn from the active theme as the user changes, stored in the database, will be used.
WordPress will look for templates in the following order, using the one it finds first:
- user (Site Editor)
- active theme
- parent theme (if a child theme is active)
The file extension and location of files within the theme directory will depend on the type of theme you are creating. A classic theme will have PHP files, typically located in the theme’s root directory, while a block theme will have HTML files in a folder named “templates”.
Template names are referenced below without file extensions. File extensions will be either .php for the classic themes or .html for block themes.
Templates for latest posts as homepage
WordPress will use the first template found for the homepage from the following list:
- front-page
- home
- index
Templates for a static homepage and posts page
When a static page is selected for the homepage display, a homepage and posts page can be set from a list of published pages on the site. The page specified in the homepage option will be displayed at the site root.
If a static page is set for the homepage, WordPress will use the first template found for the homepage from the following list:
- front-page
- custom page template (set at page level)
- page
- singular
- index
There are just two potential template options for a static posts page:
- home
- index
A published page set as the posts page will not use a custom page template. Generally, this page will not display a page title or content unless the template includes the page title and content explicitly.
Front-page template
The front-page template is one template that benefits from a special mention. If a front-page template exists anywhere in the chain of template sources, it will be used as the homepage template regardless of Reading settings or any custom template assigned at the page level. It is because of this, a front-page template may not be the best choice for every theme.
The primary use case for a front-page template would be for a theme or site that should have a page-style view from the moment of activation, no matter the state of the reading settings. One use-case could be for a dynamic homepage that differs from a traditional latest posts page. Alternatively, a site with a specific homepage design could benefit from using a front-page template.
Static posts page
When assigning the latest posts to a static page, the front-end view will not generally display the page title or content as if it were a standard page. It will, instead, derive the content from either the home template or the index template. The page acts as a placeholder, allowing the templates to display the latest posts.
The WordPress template hierarchy is a powerful part of the theme engine for WordPress, whether you are building a Classic theme, a Block Theme, or using the Site Editor to customize or extend an existing theme. This post covers just a brief look at one aspect of the template hierarchy.
How will you use the Home and Posts templates in your next project? Feedback and comments are welcome below.
Resources to learn more
- A beginner’s guide to the WordPress template hierarchy (WordPress TV)
- Template Hierarchy (Documentation)
- Theme Handbook (Documentation)
Props to @greenshady, @bph and @webcommsat for review
Leave a Reply