Update and align template descriptions

[jameskoster]

Now that we're beginning to get a better understanding for where these descriptions will appear, we can begin to refine them.

This PR makes the language used across descriptions consistent, and in some cases significantly shortens them.

Template	Before	After
Index	The default template used when no other template is available. This is a required template in WordPress.	Displays posts.
Home	Template used for the main page that displays blog posts. This is the front page by default in WordPress. If a static front page is set, this is the template used for the page that contains the latest blog posts.	Displays as the site's home page, or as the Posts page when a static home page it set.
Front Page	Template used to render the front page of the site, whether it displays blog posts or a static page. The front page template takes precedence over the "Home" template.	Displays as the site's home page.
Singular	Template used for displaying single views of the content. This template is a fallback for the Single, Post, and Page templates, which take precedence when they exist.	Displays a single post or page.
Single Post	Template used to display a single blog post.	Displays a single post.
Page	Template used to display individual pages.	Displays a single page.
Archive	The archive template displays multiple entries at once. It is used as a fallback for the Category, Author, and Date templates, which take precedence when they are available.	Displays post categories, tags, and other archives.
Author	Archive template used to display a list of posts from a single author.	Displays latest posts written by a single author.
Category	Archive template used to display a list of posts from the same category.	Displays latest posts in a single post category.
Taxonomy	Archive template used to display a list of posts from the same taxonomy.	Displays latest posts from a single post taxonomy.
Date	Archive template used to display a list of posts from a specific date.	Displays posts from a specific date.
Tag	Archive template used to display a list of posts with a given tag.	Displays latest posts with a single post tag.
Search	Template used to display search results.	Displays search results.
Privacy Policy	na	Displays the privacy policy page.
404	Template shown when no content is found.	Displays when no content is found.

Before

After

Some of the changes are simple optimisations. Others are more profound, like the Index template. In php themes, it is standard practise for the index template to serve as a fallback by programatically detecting if the visitor has requested an archive or a single post, and then acting accordingly. In the block theme paradigm this is not possible, making the Index template more singular in its purpose.

[jameskoster]

Perhaps this is an appropriate place to discuss the Index template :) Fleshing out those thoughts a little more...

In the WP template hierarchy, Index is used as a fallback when any of the following templates do not exist:

• Archive
• Singular
• Home
• 404
• Search

In php themes it is capable of fulfilling this role by including logic to determine what the visitor has requested on-the-fly.

In block-theme world, this doesn't work so well because the template cannot contain this logic. Consider a block theme that only supplies an Index template...

• If you visit an archive, you'll see the appropriate posts ✅
• If you search, you'll see the appropriate posts ✅
• If you visit a single post or page, you'll see the query format from Index, containing that single post. So unless that format displays the full post content (many only display the excerpt), it's not possible to actually view the full post / comments etc ❌
• If you visit a page that cannot be found (404), you will see just the header and footer ❓

All that to say, in block-theme world the Index template takes on a more singular purpose, so perhaps it can have a more intuitive name when it appears in the UI?

Essentially, Index is useful for:

• Acting as a fallback when no Archive template exists.
• Displaying latest posts either:
  • When the homepage is configured to display latest posts.
  • A static homepage is set, but a posts page is specified.

In that light, perhaps Index can simply be called "Posts"? This would make the minimum required posts for a block theme:

• Posts
• Singular (or single + page)
• 404

Which seems a little more intuitive than the current setup.

[kjellr]

If you visit a single post or page, you'll see the query format from Index, containing that single post. So unless that format displays the full post content (many only display the excerpt), it's not possible to actually view the full post / comments etc ❌

Isn't that the case with classic themes too, though? If my theme was just an index.php template that used the_post_except(), that's all that would be shown on a single post page.

Either way, I think the "Posts" framing makes sense. index is such a technical term — I'm not sure it'll make sense to users otherwise.

[SeywardDarby]

Editorial here. Sorry for the delay in sending notes. Here they are, in bold.

INDEX
Note: It seems like there's still some discussion about how to frame this. My 2 cents is that this works: "Posts / Displays latest posts."

HOME
Edit: "Default home page displaying latest posts. If the Front Page template is used to set a static home page, this becomes the template for the Posts page."

SINGULAR
Note: So Singular only displays when neither Single (Post) nor Page is in use? In that case, I would suggest, "Default template for displaying a single piece of content when the Post or Page template isn't in use."

SINGLE
Edit: Change the name of this template to "Post"
(FWIW, if you do this, you can also change "Singular" to "Single"—which sounds better anyway!)

FRONT PAGE:
Edit: "Displays as the site's home page."

CATEGORY:
Edit: "Displays latest posts in a single category."

TAG
Edit: "Displays latest posts with a single post tag."

[jameskoster]

Isn't that the case with classic themes too, though? If my theme was just an index.php template that used the_post_except(), that's all that would be shown on a single post page.

That is indeed the case, but I don't think anyone building a theme for general consumption would do that? The wp.org theme review guidelines say this about Index:

If you only include this template file [Index], it must include all functionality of your theme.

Since block templates cannot perform any logic, it would not be possible for index.html to "include all functionality" of the theme. Therefore, a block theme consisting of only index.html wouldn't really work for a typical WordPress site, and consequently I don't suppose such a theme would be acceptable in the theme directory.

[jameskoster]

@SeywardDarby Thank you! A couple of thoughts:

Default home page displaying latest posts. If the Front Page template is used to set a static home page, this becomes the template for the Posts page.

I'm not sure that this description for the Home template is quite right.

Home becomes the template for the posts page regardless of whether the Front Page template exists or not. Perhaps we could revise:

Default template for displaying latest posts. If the home page is set to a static home page, Home becomes the template for the Posts page.

This still doesn't feel quite right though... for that second use case, "Home" feels like a really contradictory name. I wonder if we can come up with something better. This all kind of ties in with the discussion around the Index template. In the block theme world, I'm not really sure we need both Index and Home – they're both serving the same purpose. We may need to work on these two particular templates in isolation.

So Singular only displays when neither Single (Post) nor Page is in use?

Singular will only ever be used if Single or Page don't exist at all. It's useful when a theme author wants to use the exact same template for posts and pages. So perhaps this can just be:

Default template to display a single post or page.

---

Changing "Single" to "Post" makes sense to me. Edit: Just remembered that we already updated the name of this one to "Single Post" :D

[jameskoster]

Perhaps a better way to frame Index / Home:

Index will resolve to display any archive when archive.html is not present, IE it may not always be latest posts. So we could give it a non-specific name like "Posts", and a very simple description:

Displays posts.

The unique feature of the home template is that it will always display latest posts, whether that is because it resolves for the homepage, or the posts page when a static page is set as the homepage. So perhaps we can call the home template "Latest posts" with the description:

Displays as the site's home page, or as the Posts page when a static home page it set.

[shaunandrews]

I love seeing these become shorter and more succinct. However, I do wonder if there's some way to avoid and reduce the repetitious use of the word "Displays" for every template description.

[jameskoster]

Yeah it would be good to optimise that. We can probably lose the "Displays" prefix for the list view use case:

But we'd need to account for other areas in which the description appears too. Obviously this doesn't work very well:

[SeywardDarby]

Hi. Sorry to be slow to chime back in here. If you would like me to review revised text, please let me know and point me to the latest version (ideally in a Google doc if one exists/can be made). One thought for the list view: The shortened versions could work well, but we'd need to be consistent about the grammar and syntax, and singular versus plural. For instance, right now we have "Page: Individual Pages" and "Single: A single blog post," which aren't stylistically consistent. Something like "Page: A single page" and "Post: A single blog post" would be consistent.

Again, please let me know if you would like me to review revised text in full. Thanks!

[jameskoster]

The descriptions in the OP are the latest versions :)

I think it will be tricky to eliminate the repetitious "Displays..." prefix and still have the descriptions adaptable to different contexts.

[SeywardDarby]

OK. A few questions:

• Is it possible to have different descriptions for different locations, or do they need to be standardized? (e.g. could you have "Displays a single page" in one place, and "A single page" in another place?)
• Would it be possible to interchange terms such as "show" and "present" with "display," or is "display" the only verb that works in this context?

[jameskoster]

I think it's possible, but would need a dev to confirm. The trade-off is there's twice as much to translate. I don't know if it's worth it.

Would it be possible to interchange terms such as "show" and "present" with "display," or is "display" the only verb that works in this context?

Sure. Words like 'display' and 'render' appear quite a lot in the current template documentation. I suppose 'render' is technically the correct term, but I figured 'display' was more user-friendly. Perhaps it's ok to use 'render' though, seeing as template editing is a more advanced feature. Of course 'show' and 'present' work too :D

[carolinan]

Describing the index is tricky, but I think displaying posts is the most common result when the index is used as a fallback.

[jameskoster]

We can continue to refine. If this makes it in to the beta we'll hopefully get feedback :)

[youknowriad]

I noticed that the descriptions on Core are different from these ones. Please don't forget to add the "backport to WP beta/RC" label in 5.9 targeted PRs otherwise, these changes will get lost in the future.

[youknowriad]

I added the label back to sync the wp/trunk branch. (this is already in core now)

[paaljoachim]

@jameskoster is working on updating the template names in this PR:
#51428
Head on over and take a look and give some feedback.