Add a heading() Twig function

[mmikkel]

Rendering correct heading hierarchies can be challenging when working with modular content, and has arguably become even more difficult as Craft 5 has freed developers up to nest, embed and render() blocks, modules and components a lot more freely than before.

So for a while now, I've used this pattern a lot:

{{ include('some-partial.twig', {
    heading: 'Great heading',
    headingLevel: 3
}) }}

...

{# some-partial.twig #}
{% set headingLevel = headingLevel ?? 2 %}

{{ tag("h#{headingLevel}", {
    class: 'text-large',
    text: heading
} }}

The idea here is that I can pass a headingLevel into a partial, and use the tag() function to render a heading tag at the appropriate level, using a simple string interpolation for the @tag param.

This way, I can have a default heading level per partial (like in the above, where the default would be a <h2>), but I'm able to override that default so that if the partial is ever renderer deeper down into a document structure, I can easily make the heading into a <h3> or <h4> instead – for example.

The tag() function works pretty well for this – especially compared to the "old" way of doing the same thing, i.e. something like <h{{- headingLevel -}}>{{ heading }}</{{- headingLevel }}> 😬 – but the syntax leaves something to be desired; it gets kinda hard to read, has no proper highlighting and is easy to mess up.

Craft already ships with some dedicated tag-rendering functions, like ul(), ol and input() - considering the above, it would be cool if a heading() (or h() 👀) function could be added, which was basically just a wrapper around tag(), but where the first param was the desired heading level (int 1-6), instead of a HTML tag.

Personally, I think this would look pretty clean:

{{ heading(headingLevel, {
    class: 'text-large',
    text: heading
}) }}

{# ☝️ ... would render <h2 class="text-large">Great heading</h2> #}

[brandonkelly]

Good idea! Just added this for 5.10: #18524