Allow themes to add custom templates description

[iamtakashi]

Themes can add custom templates, but there doesn't seem to be a way to add descriptions. @jffng kindly looked into this for me, and it seemed like name, title, and postTypes are allowed at the moment.

gutenberg/schemas/json/theme.json

Line 1559 in 40efcbe

"name": {

The screenshot was from a site with Twenty Twenty-Two, but many other themes also have no way of clarifying the custom template. The description will help theme builders to communicate with the user what the custom templates are for.

I've briefly looked for a request opened before but couldn't find it. If there is somewhere, kindly point me to the conversation. Thanks in advance!

[github-actions]

Hi,
This issue has gone 30 days without any activity. This means it is time for a check-in to make sure it is still relevant. If you are still experiencing this issue with the latest versions, you can help the project by responding to confirm the problem and by providing any updated reproduction steps.
Thanks for helping out.

[iamtakashi]

Thanks, @talldan, for removing the stale tag.

I still think it'd be helpful for both themers and users if we could add descriptions to custom templates.

[mikemcalister]

As we see more work happening on the Site Editor view, it would be great to see these descriptions added to help with consistency in the Template view.

Further, the ability to easily create templates within the admin means users may add more templates than they have historically. Having a way to describe these templates for themselves and other users will be a necessity.

[talldan]

Also related - Browse mode: Consider adding in descriptions of template after selection #46640.

[fabiankaegy]

Actually after investigating this a bit more the customTemplates key in theme.json isn't actually whats used for the title / description here. Instead it is this filterable list here: https://github.com/WordPress/wordpress-develop/blob/ca0260b5beaab6666e8f9fe0a9bff0ca8f6ac228/src/wp-includes/block-template-utils.php#L109-L184

So you can add your custom templates including description like so:

add_filter( 'default_template_types', 'add_custom_template_types', 10, 1 );

/**
 * Add custom template types.
 *
 * @param array $templates The default template types.
 *
 * @return array The modified template types.
 */
function add_custom_template_types( $templates ) {

	$templates['single-podcast'] = [
		'title'       => __( 'Single Podcast', 'namespace' ),
		'description' => __( 'A single podcast post.', 'namespace' ),
	];

	return $templates;
}