"Home" template name can be confusing

[jameskoster]

The name "Home" suggests the template will display the site homepage. This is true when in the reading settings the site is configured to display latest posts on the front page. But if a static front page is set, then Home will display the Posts Page, not the homepage.

The description helps a bit:

Displays posts on the homepage, or on the Posts page if a static homepage is set.

But perhaps the name itself could be clearer... something like "Blog home"? Or could the name be dynamic based on the homepage settings?

[autumnfjeld]

This would be an amazing improvement, "home" is very overused in so many contexts. And in this case very misleading as you point out as its role is to display posts, which may or may not be on the user's "homepage"(aka root page/landing page)

Looking at these docs maybe blog-posts-index or blog-posts is a good name. I don't think it should include the word home

But if a static front page is set, then Home will display the Posts Page, not the homepage.

Do you mean: "But if a static front page is set, then home.html template will display on a posts page, not the front page (or root page).

I was a little confused by the term "Posts Page". I don't see any special naming for that here https://developer.wordpress.org/themes/basics/template-hierarchy/#home-page-display.

[alaczek]

Do you mean: "But if a static front page is set, then home.html template will display on a posts page, not the front page (or root page).

Yes, this is exactly how it works.

[jameskoster]

Sorry for the confusion. "Posts page" refers to the option in the reading settings:

In the configuration above, the "Blog" page serves as the Blog Posts Index Page, and will resolve to display the Home template if it exists.

Looking at these docs maybe blog-posts-index

Blog Posts Index could work, although Index isn't the most intuitive word. Perhaps there's an alternative word we could use, that could also apply to the Index template itself? 🤔

[autumnfjeld]

Thank you for adding the extra context of the Reading Settings. :)

Blog Posts Index could work, although Index isn't the most intuitive word

Maybe blog-posts.html (blog-posts.php) is the most straightforward template name.

[tanjoymor]

This is an old issue, but in light of the recent pull request: https://github.com/WordPress/gutenberg/pull/52048 I wanted to note my concerns with changing the name of the "Home" home.html template to "Blog Home".

With many current themes that have designed a static homepage look using the “Home” template, renaming it to “Blog Home” feels like a step backwards. There’s going to be a whole lot of users saying “Why is my homepage now a blog? I didn’t want that.” (Even though it’s just a name.) I have already encountered users asking how to build a website because they don’t want a blog. And one user got particularly upset that some rarely used global management page is called “My Blog” because they didn’t want a blog.

I had mentioned several times, months ago, that the name wasn’t the issue, it was how the templates were being used in theme designs that was the problem. In my opinion, a theme should be designed to use the “Index” template if the homepage is going to be a blog (and not activate the Home template) and use the “Home” template if the homepage is going to be a static website design. But it never happened.

This name change basically just reverses the problem, it doesn’t really solve it.

[annezazu]

@WordPress/gutenberg-design ^ curious about what we can do in light of this feedback. I'm going to keep the issue closed for now as what was described is addressed but it's worth discussing the root problem. In theory, this change could, going forward, help themes have better practices but the problem remains for current themes.

[tanjoymor]

As part of the potential discussion, I’m curious how keeping the name change might help with better practices moving forward? If a theme designer wants to create a website first theme with a homepage that presents as a static homepage, which template would they use? And how would that same theme also offer a default blog/posts page? (I have thoughts, but previous suggestions on that were also dismissed.)

[jasmussen]

CC: @jameskoster for additional context. But the base motivation for this is to keep the template names as understandable as possible for users who never touch the actual code, people who might not know that the same template is called home.php in classic themes, or home.html in block themes. In that case, "Home" has commonly been confused for its behavior in comparison with "Front Page", and the addition of "Blog" but keeping the term "Home" is meant to alleviate that confusion.

However a followup is meant to be an enhancement of the template detail view, where we can have a pretty verbose description of the particular template and its behavior, including verbiage such as Blog Home, also known as "Home" [...].

[jameskoster]

With many current themes that have designed a static homepage look using the “Home” template

This is an unfortunate mis-use of the Home template, according to the template hierarchy. It's purpose is to display the latest posts (IE the "blog"), either as the site homepage, or as a separate "Blog" page when a static homepage is configured in the reading settings. I don't think it would be responsible to cater to unorthodox use cases in the template name.

If a theme designer wants to create a website first theme with a homepage that presents as a static homepage, which template would they use?

If the theme is publicly available then it has a responsibility to serve both uses cases ("blog" or "website") out of the box. It should not dictate the homepage behavior – that's a decision taken by the user via reading settings. If such a theme wants to offer a "static homepage" template, that should be done as a $custom template. Alternatively the Front Page template can be used, but it also needs to include a Query Loop to serve as a blog too.

The main motivation for the recently-merged change is to delineate between "Front Page" and "Home", which were very easy to conflate. Hopefully adding the "Blog" prefix will help folks understand the templates purpose a bit better.

[tanjoymor]

@mtias

If such a theme wants to offer a "static homepage" template, that should be done as a $custom template.

I thought this was strongly frowned upon and being discouraged?

@jameskoster

The main motivation for the recently-merged change is to delineate between "Front Page" and "Home", which were very easy to conflate.

True. However, while clarifying this situation, it does introduce a different confusion for users.

When a theme is built it needs to represent either a blog first approach or a website first approach. It can’t do both at the same time. If “Home” is supposed to be viewed as a “Latest Posts” page (which is the old way of doing things), how is that giving the user the control and choice of whether they are presenting a website homepage or a blog homepage?

How does a user turn what you’ve described into a “website without a blog”? If my first question above is true.

Alternatively the Front Page template can be used, but it also needs to include a Query Loop to serve as a blog too.

Not all users want a blog in their website.

There is contradictory guidance and opinions being provided to those who design themes.

At least with a name of Blog Home, it could be explained to users as meaning that this template could be either a blog or static homepage. So there is that.

If opinions have changed since last October, and themes should in fact be designed using a $custom template for a “website” focused theme, then this is indeed a moot point, but it is not widely known or understood.

Unfortunately, there is currently a mix in how Block themes have been designed. All of these scenarios exist:

• Index only (no Home); presents as a blog
• Home and Index; Home presents as a blog or static page; Index is ignored for either homepage or posts page (because of hierarchy) — if the posts page is set while Home is assigned to the homepage both pages use the same Home template — if a static homepage is set with a $custom template and the posts page is set, and the Home template has been designed to look like a static page then the posts page looks like a static homepage not a blog page
• Front Page hijacks all homepage settings, users cannot create a static homepage using a $custom template; posts page will use either Home or Index depending on what is active
• Homepage is created using a page with a $custom template; posts page will use either Home or Index depending on what is active

It seems the reason for this mixture is because of the understanding some have with regards to my first question above. Strong opinions were expressed that homepage content should not be built in a page, but should be built in a template by default.

Users are not able to remove or disable any templates that come pre-installed and activated with a theme. So they have to work with what the theme provides as a base. If the Front Page template is active on install there is nothing a user can do about that.

Where might I find the documentation that provides for best practices on building a Block theme for those creating themes for public use? The Template Hierarchy document you’ve linked to is based on Classic themes and doesn’t provide best practice guidance.

[jameskoster]

If “Home” is supposed to be viewed as a “Latest Posts” page (which is the old way of doing things), how is that giving the user the control and choice of whether they are presenting a website homepage or a blog homepage?

It's not just "supposed to", that is it's only purpose according to the template hierarchy (which applies to all themes, not just classic themes). The users choice is in the reading settings — to create a "website without a blog" you set the front page to display a static page. The assigned page will resolve to display template: Front Page → $custom → Page-$slug → Page → Singular → Index.

[tanjoymor]

I agree that this has always been the case. The introduction of Block themes, the Site Editor, and access to the templates has changed the thinking and use around this. Perhaps the documentation about template hierarchy and usage is in need of some updates? Things can and do work differently now. I’m not sure that we can realistically control how theme developers and users use the templates in practice and we might be creating unnecessary friction by not evolving with them and the software. Unless we want to implement stricter controls that prevent the templates from being used in ways that differ from Classic themes.

[annezazu]

Where might I find the documentation that provides for best practices on building a Block theme for those creating themes for public use? The Template Hierarchy document you’ve linked to is based on Classic themes and doesn’t provide best practice guidance.

Just noting this for @justintadlock as you begin work on the Theme handbook and this will inevitably come up.

[justintadlock]

Where might I find the documentation that provides for best practices on building a Block theme for those creating themes for public use? The Template Hierarchy document you’ve linked to is based on Classic themes and doesn’t provide best practice guidance.

Just noting this for @justintadlock as you begin work on the Theme handbook and this will inevitably come up.

I've made a note of the template hierarchy. I'll actually begin tackling some documentation related to templates soon.

For more info on the question around documentation: there is a new Theme Handbook overhaul project that's underway: https://github.com/WordPress/Documentation-Issue-Tracker/issues/816

Several new pieces of documentation are there for getting started, but we're far from finished. These are unpublished at the moment, but you can click on the individual ticket links to read through (also, I'd love to see any and all feedback on those tickets, especially from folks learning block theming for the first time).

In the existing handbook, there's a small chapter dedicated to block themes, so that's definitely worth checking out at the moment: https://developer.wordpress.org/themes/block-themes/

Full Site Editing is another great resource: https://fullsiteediting.com/

There's also a lot of great tutorials and courses on Learn WP: https://learn.wordpress.org/?s=block+themes