Problem/Motivation
It is becoming increasingly clear, both throughout core and in contrib, that Twig templates need the ability to associate contextual metadata with them.
Typically, in the past, this has been done using standalone/custom YAML files (like with layouts: *.layouts.yml). Previously, in the case of help_topics this metadata was being embedded using HTML <meta> tags inside the templates themselves (this has since been switched to using a stand-alone front matter implementation in anticipation of this issue).
While this technically works and is filtered out during XSS processing, it creates yet another coding paradigm FE developers have to be aware of. The primary reason this was done was to keep the relevant information with the template it is associated with.
From @alexpott in #2920309-321: Add experimental module for Help Topics:
Having to define a help topic in both a yaml file and then create a separate twig template was bothering me. The reason we went for annotations was to keep the discovery along with the code. I think the same rule appears here.
Suffice it to say: we need a standardized way of associating inline metadata with templates.
Potential existing use cases
- #3075432: [PP-1] Inline .layouts.yml definitions with each template
- #3069109: Replace help_topic meta tags with front matter
Being able to associate metadata with a template can also lend to newer innovations for problems we've had in the past.
Potiential new use cases
- #2547363: Use front matter to version templates - Having the ability to "version" templates, whether it be against their own versions or and external framework like Bootstrap, would be invaluable
- #3050386: Allow loading CSS and JavaScript directly from templates - Being able to associate assets with a specific template (similar to how web components work) could help the "overrideability" should a [sub-]theme choose to take ownership of it.
- Template variations (A/B testing)
There are many ideas of how we can help alleviate BC issues with Twig templates, almost all would likely require the ability to provide some sort of metadata with them; if only for some sort of identification, filtering, or sorting purposes.
Proposed resolution
Allow the use of Front Matter YAML blocks at the top of template files.
Front Matter was made popular by Jekyll and has since become sort of the "industry standard" way of associating metadata with any sort of document.
- https://jekyllrb.com/docs/front-matter/
- https://developers.google.com/web/resources/yaml-and-attr-reference
- https://indieweb.org/frontmatter
- https://learn.getgrav.org/16/content/headers
- https://gohugo.io/content-management/front-matter/
- https://middlemanapp.com/basics/frontmatter/
Remaining tasks
Create patchCreate tests
Note that the framework manager review of this approach was done in comment #160. The framework managers decided that this approach (putting the front matter in YAML format at the top of files, and not enclosing it in comments or other delimeters) was the best approach to use. There was a lot of discussion of the pros and cons of this and other approaches... There was an attempt at a summary in comment #134, and then a bunch of additional discussion, then another summary in comment #157.
User interface changes
None
API changes
None
Data model changes
None
Release notes snippet
A new component has been created to parse front matter from sources. See the change record for more information.