Add template descriptions via Twig comment syntax

[Copilot]

Users with many templates struggle to identify the right template from dropdown names alone. Short names lack context, long names become unwieldy.

Implementation

Templates can now include inline descriptions using Twig comment syntax:

{# @description: Paginated blog listing with featured image and excerpt #}
{% for entry in craft.entries.section('blog').all() %}
    <article>{{ entry.title }}</article>
{% endfor %}

Descriptions appear in the dropdown next to template names using an em-dash separator.

Changes

• TemplateHelper: Added extractTemplateDescription() method

  • Reads first 8KB via file_get_contents with max length
  • Regex pattern /{#\s*@description:\s*(.*?)#}/is supports # characters (hashtags, hex colors)
  • HTML-escapes output for XSS protection
  • Normalizes whitespace for single-line display

• TemplateSelectField: Extracts and appends descriptions to option values during template enumeration

• README: Documented syntax with examples

Compatibility

Backward compatible—templates without descriptions display unchanged.

[!WARNING]

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• asset-packagist.org
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/c0lht0 /usr/bin/composer install (dns block)
  • Triggering command: /usr/bin/php8.3 /usr/bin/php8.3 -n -c /tmp/9z16Qf /usr/bin/composer install --no-interaction (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Description of template.</issue_title> <issue_description>I have a lot of templates that user can select. It is very hard to them to remember every single of them and it is hard no me to select a name for the templates that describe them. If I want to make a good description the name become really long.

It is possible to make some kind a Description field/col/zone where it is possible to write a description for the template?</issue_description>

<agent_instructions>Theorize about how we can enable descriptions for Twig templates. A few ones: .txt file with template name + .description? A twig comment inside the file? Something else?</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes sjelfull/craft3-templateselect#5

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.