Update template descriptions with more detail

[richtabor]

Now that the 6.2 Site Editor is introducing a drill-down for individual templates, let’s revisit the current descriptive text for each template type. These don't have to be limited to small bits — but rather provide details, and context, on the workings of the selected template.

We'll need to update the descriptions in get_default_block_template_types() — referencing content from the template hierarchy.

Visual

[richtabor]

Related: #36000

[jordesign]

I think there is a HUGE opportunity here for the copy to help with clarity around some of the potential confusion around the use of Home/Index/Front Page - and other things like that.

[jameskoster]

We might want to consider grouping this task with one or two others, or at least having some designs prepared. With longer descriptions the Add Template menu is going to become very noisy:

If we introduce some grouping for templates (as discussed in #44302) then perhaps we can omit the description in the Add Template menu, and defer the description to the pattern selection modal, something like:

It's important to keep such grouping in mind for this task as well because it might affect the description. For example when the Home template exists within the 'Blog' group, it's purpose is more inherently apparent.

Just for completeness, the template description also appears in the Inspector, the document details popover, and the template management table. But a change in description length probably won't affect these too badly.

[carolinan]

Related:

https://core.trac.wordpress.org/ticket/57562
https://wordpress.org/support/topic/index-template-2/

The templates list currently indicates that the Index template "Displays posts."
The Issue
However, since there are more specific templates in this theme like Home, Archive, and Search, in practice, the Index template is just a fallback. In my testing, I could not find any instance of this template actually being used.
Suggested Improvement
Could we revise this wording to make it clearer that this is only a fallback?
Perhaps something like this, but certainly open to better wording:
"Fallback template, displays posts only if no other template applies."

[SaxonF]

Is 6.2 the right time to introduce template drill-down? Might be a little redundant without extra details, including which pages are using a particular template. It also means extra clicks for quickly previewing different templates. Perhaps a dedicated info button or similar could drill-down in future?

[jasmussen]

Is 6.2 the right time to introduce template drill-down? Might be a little redundant without extra details, including which pages are using a particular template. It also means extra clicks for quickly previewing different templates. Perhaps a dedicated info button or similar could drill-down in future?

The drilldown is key to actually showing the edit button in context, so I think we do need it for 6.2 yes.

[jameskoster]

Here's an initial take on this, inspired partially by existing documentation:

Template	Description
Front Page	Renders your site’s front page, whether it is set to display latest posts or a static page. The Front Page template takes precedence over the Home template.
Page	The template used to render all static pages, unless a custom template has been applied, or a dedicated template exists.
Attachment	Displays when a visitor views the dedicated page that exists for any attachment uploaded to a post.
Singular	Displays any single entry such as a Post or a Page. Also serves as a fallback when a more specific template (e.g. Single Post, Page, or Attachment) cannot be found.
Privacy Policy	Renders your site’s Privacy Policy page. The Privacy Policy page template takes precedence over the static Page template.
404	Displays when a visitor views a dead link. This can happen if the content was deleted, or the visitor made a typo.
Custom	A custom template can be manually applied to any Post or Page.
Home	If WordPress cannot find the Front Page template and “your latest posts” is set in the front page display settings, then Home will be used. Additionally, WordPress will look for this template when the posts page is set in the front page displays section.
Index	Displays when “your latest posts” is set in the front page displays settings, and when the Home template cannot be found. Additionally; this is the default template for any page on your site that doesn’t have another template applied.
Single Post	This template will be used to display all the posts on your website, unless a custom template has been applied to that post, or a dedicated template for that post exists.
Category	Displays a post category archive. Serves as a fallback when more specific template (e.g. Category: Recipes) cannot be found.
Tag	Displays a tag archive, IE when a visitor wants to view all the posts with a given tag. Serves as a fallback when a more specific template (e.g. Tag: Pizza) cannot be found.
Date	Displays a post archive when a specific date is visited, e.g. yoursite.com/2023/
Author	Displays any archive of posts written by a single author. Serves as a fallback when a more a specific template (e.g. Author: Admin) cannot be found.
Taxonomy	Displays any custom taxonomy. Serves as a fallback when a more specific template (e.g Taxonomy: Art) cannot be found. A Taxonomy is a fancy word for the classification / grouping of things. Taxonomies have Terms which serve as the topic by which you classify / group things. For example: a Taxonomy named “Art” can have multiple Terms, such as “Modern” and “18th Century”.
Archive	Displays any archive, including posts by a single author, categories, tags, taxonomies, custom post types, and posts in a given date range. Serves as a fallback when more specific templates (e.g. Category or Tag) cannot be found.
Search	Displays when a visitor performs a search on your website.

[jameskoster]

Perhaps @WordPress/block-themers has some thoughts on these descriptions? 🙏

[jasmussen]

High level, looks good. A few quick ones:

• "The Privacy Policy page template takes precedence over the static ‘Page’ template." — do we need the single quotes on Page?
• e.g. yoursite.com/2023/ — can we use "example.com" instead? If people copy paste the yoursite.com URL it leads to an actual website, whereas example.com was created for documentation purposes.
• The taxonomy description might be nice to reduce to 3 paragraphs. Quick fix, just merge the first and second paragraphs. Also, should we just write "A Taxonomy is another word for the classification / grouping of things." instead of "fancy"?

A few meta comments about this issue, and about for anyone reviewing:

• It's pretty important we land this one for 6.2, so let's keep things flowing. It would be better to land an improvement that isn't perfect, and refine it further for 6.3, than not land anything.
• It's okay that descriptions here get a bit more verbose and long, becasue the drilldown detail pages in the refreshed site editor afford space for text. It's always good to be precise of course, but we also don't have to compress it to bits.

[jordesign]

Towards consistency of wording...
Should we consider:

Front Page: Displays your site’s front page....

Page: The template used to display all static pages....

Privacy Policy: Displays your site’s Privacy Policy page.

[jameskoster]

do we need the single quotes on Page?

I don't think so 👍

can we use "example.com" instead?

Sure!

instead of "fancy"?

Haha, I took that from the wp.org documentation, but yes it stood out to me as well.

Updated descriptions:

Template	Description
Front Page	Displays your site’s front page, whether it is set to display latest posts or a static page. The Front Page template takes precedence over the Home template.
Page	The template used to display all static pages, unless a custom template has been applied, or a dedicated template exists.
Attachment	Displays when a visitor views the dedicated page that exists for any attachment uploaded to a post.
Singular	Displays any single entry such as a Post or a Page. This template will serve as a fallback when a more specific template (e.g. Single Post, Page, or Attachment) cannot be found.
Privacy Policy	Displays your site’s Privacy Policy page. The Privacy Policy page template takes precedence over the static Page template.
404	Displays when a visitor views a dead link. This can happen if the content was deleted, or the visitor made a typo.
Custom	A custom template can be manually applied to any Post or Page.
Home	If WordPress cannot find the Front Page template and “your latest posts” is set in the front page display settings, then Home will be used. Additionally, WordPress will look for this template when the posts page is set in the front page displays section.
Index	Displays when “your latest posts” is set in the front page displays settings, and when the Home template cannot be found. Additionally; this is the default template for any page on your site that doesn’t have another template applied.
Single Post	This template will be used to display all the posts on your website, unless a custom template has been applied to that post, or a dedicated template for that post exists.
Category	Displays a post category archive. This template will serve as a fallback when more specific template (e.g. Category: Recipes) cannot be found.
Tag	Displays a tag archive, IE when a visitor wants to view all the posts with a given tag. This template will serve as a fallback when a more specific template (e.g. Tag: Pizza) cannot be found.
Date	Displays a post archive when a specific date is visited, e.g. example.com/2023/
Author	Displays any archive of posts written by a single author. This template will serve as a fallback when a more a specific template (e.g. Author: Admin) cannot be found.
Taxonomy	Displays any custom taxonomy. A Taxonomy is another word for the classification / grouping of things. Taxonomies have Terms which serve as the topic by which you classify things. For example: a Taxonomy named “Art” can have multiple Terms, such as “Modern” and “18th Century”. This template will serve as a fallback when a more specific template (e.g Taxonomy: Art) cannot be found.
Archive	Displays any archive, including posts by a single author, categories, tags, taxonomies, custom post types, and posts in a given date range. This template will serve as a fallback when more specific templates (e.g. Category or Tag) cannot be found.
Search	Displays when a visitor performs a search on your website.

[bph]

a few suggestions for clarity. For others, I would need to think some more...

• 404 - Displays when a visitor tries to visit a non-existing page, for instance she followed a dead link or made a typo

• Search - Displays the results from keyword search

• Archive - Displays any a collection of posts, and serves as a fallback when more specific templates cannot be found.

• Privacy Policy - Displays your site’s Privacy Policy page.

• Home - Displays latest posts, also fallback when Front page template is not found.

• Index - Fallback for any page that doesn't have a template, including Home or latest posts.

• Category - Displays a post category archive, unless there is a more template for a specific category.

• Singular - Displays any single entry such as a Post or a Page, unless there is a more specific template.

• Tag - Displays all the posts with a given tag.

• Author - Displays a list of posts for all authors, unless there is a template for a single authors

• In the first version you probably could leave out "This template will serve as a fallback ... " part out.

[melchoyce]

One thing I've been personally confused about while designing block themes is the difference between Front Page and Home, so any additional context that could be added here could be really helpful.

[justintadlock]

I've made several adjustments to the table above, primarily cleaning up some of the copy. Some of it I have simplified by just making descriptions consistent. Others, I added a couple of different takes. There were also some inconsistencies with the usage of uppercase, and I wasn't sure how to proceed. So, I used my best judgement, preferring uppercase only when referencing a specific title or template name.

One important note on the earlier text: "e.g." should be followed by a comma (e.g., something). It's the same as "for example, something." I'm not sure if we have a stylebook mention of this, but it is in both the Chicago and AP stylebooks.

We could also really shorten the taxonomy template description if we left out the definition of what a taxonomy is. Otherwise, it's just long. Are links to support documents possible here?

Template	Description
Front Page	Displays your site's front page, whether it is set to display latest posts or a static page. The Front Page template takes precedence over all templates.
Page	Display all static pages unless a custom template has been applied or a dedicated template exists.
Attachment	Displays when a visitor views the dedicated page that exists for any media attachment uploaded to a post.
Singular	Displays any single entry, such as a post or a page. This template will serve as a fallback when a more specific template (e.g., Single Post, Page, or Attachment) cannot be found.
Privacy Policy	Displays your site’s Privacy Policy page.
404	Displays when a visitor views a non-existant page, such as a dead link or when the visitor makes a typo.
Custom	A custom template can be manually applied to any post or page.
Home	Displays the latest posts for either the site homepage or a custom page defined under reading settings. If it exists, the Front Page template overrides this template when posts are shown on the front page.
Index	Used as a fallback template for all pages when a more-specific template is not defined.
Single Post	Displays single posts on your website unless a custom template has been applied to that post or a dedicated template exists.
Category	Displays a post category archive. This template will serve as a fallback when more specific template (e.g., Category: Recipes) cannot be found.
Tag	Displays a post tag archive. This template will serve as a fallback when more specific template (e.g., Tag: Pizza) cannot be found.
Date	Displays a post archive when a specific date is visited (e.g., example.com/2023/).
Author	Displays a single author's post archive. This template will serve as a fallback when a more a specific template (e.g., Author: Admin) cannot be found.
Taxonomy	Displays a custom taxonomy archive. Like categories and tags, taxonomies have terms which you use to classify things. For example: a taxonomy named "Art" can have multiple terms, such as "Modern" and "18th Century." This template will serve as a fallback when a more specific template (e.g, Taxonomy: Art) cannot be found.
Archive	Displays any archive, including posts by a single author, category, tag, taxonomy, custom post type, and date. This template will serve as a fallback when more specific templates (e.g., Category or Tag) cannot be found.
Search	Displays when a visitor performs a search on your website.

[jameskoster]

Thanks for taking a look, this seems like a nice iteration to me. A couple of minor comments:

404

The 'typo' part is a little ambiguous... when the user makes a typo where, adding a comment, logging in, searching? Should we embellish that, or maybe get rid of it?

Attachment

It feels a little overly technical / jargony. Do we need that "uploaded to a post" part at the end?

Displays when a visitor views the dedicated page that exists for any media attachment.

Home

Displays the latest posts for either the site homepage or a custom page defined under reading settings.

Should 'for' be 'as'?

Displays the latest posts as either the site homepage or a custom page defined under reading settings.

[justintadlock]

The 'typo' part is a little ambiguous... when the user makes a typo where, adding a comment, logging in, searching? Should we embellish that, or maybe get rid of it?

My gut instinct was to get rid of it when I first read it, but I was trying to incorporate some of the existing text. Should've went with my gut. Either option would work, though. Agreed that it's ambiguous.

It feels a little overly technical / jargony. Do we need that "uploaded to a post" part at the end?

We can drop that bit. Technically, it doesn't have to be uploaded to a post, so it'd be more accurate.

Should 'for' be 'as'?

Yes, that would be better.

[sabernhardt]

I recommended a few changes to WordPress/wordpress-develop#4204, which probably would need to be in the plugin, too.

#48290 (comment)

With longer descriptions the Add Template menu is going to become very noisy

The longer descriptions also move the icons further down, away from the template name.

Align these icons to the top:

.edit-site-new-template-dropdown__popover .components-button.has-icon.has-text {
    align-items: start;
}

If the style is appropriate for all of the similar buttons, align-items: start could be added in the button component styles.

[jameskoster]

@sabernhardt this one should already be fixed in the plugin:

See: #48710

[Mamaduka]

It would be the same in WP 6.2 after package updates are merged.

[Thelmachido]

Landed here after this forum issue thank you for looking into this.

Confusing issues:-

• There is a template called blog(alternative) which suggests that there is another actual template you can use for your blog page and one can easily assume this is the Index template from its description.

Is it possible to change the description for the index template and the name of the blog(alternative) template

[carolinan]

The blog (alternative) template is available in Twenty Twenty-Three. It is a custom template.

[jameskoster]

This was closed by #48934