Hugo: Support Markdown Render Hooks for Headers

[frerich]

A useful feature provided by many web applications is the ability to conveniently get a link referencing a specific header in the page. People can then bookmark or share the link in order to reference an individual section. Consider e.g. the Effective Go page and try hovering the mouse above any of the headers with a blue background: the shown paragraph symbol is a link to the respective header. Copying the address of the link gets you the URL referencing the header.

Right now, automatically adding such anchor links is possible in Hugo by filtering the entire HTML markup of a page, e.g. given a partial add-header-anchors.html with

{{ . | replaceRE "(<h[1-9] id=\"([^\"]+)\".+)(</h[1-9]+>)" `${1}<a href="#${2}" class="header-anchor" ariaLabel="Anchor">&para;</a>${3}` | safeHTML }}

One can use

{{ .Content | partial "add-header-anchors" }}

With the advent of Markdown render hooks, this seems like a hack. Instead, it would be great if the HTML generated for headers could be customised using a hook such as layouts/_default/_markup/render-header.html

[frerich]

The proposed render-header template could be passed a context with the following fields:

• Page: The Page being rendered
• Level: The level of the header (1 for top level headers, 2 for sub-headings etc.)
• Anchor: The generated or assigned anchor for the header
• Text: The rendered (HTML) header text
• PlainText: The plain variant of the above.

With this at hand, a header such as

## Getting Started

Could be converted to a header with the paragraph icon link using something along the lines of

<h{{ .Level }}>{{ .Text }}</h{{ .Level }}><a href="#{{ .Anchor }}">&para;</a>

[kaushalmodi]

I like this proposal. Just a minor nitpick .. to call it render-heading instead of render-header as they are technically called headings in the HTML spec.

[frerich]

I concur - the CommonMark spec also talks about headings, so render-heading seems more appropriate.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. The resources of the Hugo team are limited, and so we are asking for your help.
If this is a bug and you can still reproduce this error on the master branch, please reply with all of the information you have about it in order to keep the issue open.
If this is a feature request, and you feel that it is still relevant and valuable, please tell us why.
This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.

[apexskier]

(keeping this from stale-ing)

This still would be very useful for me. It's a common feature on blogs, it lets me cross-link within my article, and it allows me to share more helpful links to other people.

[jemus42]

I am just about to fiddle this into the theme I'm using – before I do, I'd like to confirm: Does it look like this will make it into an upcoming release?

[bep]

I am just about to fiddle this into the theme I'm using – before I do, I'd like to confirm: Does it look like this will make it into an upcoming release?

I have initially been a little hesitant about this feature; not the things It tries to solve (I recently found one more thing that this feature would help with), but I have been hoping to get to a state this could be solved in a ... more elegant way (I have talked about this elsewhere).

Image and link hooks was kind of obvious -- we really needed those right away, and they have proved it's usefulness.

But since that "elegant way" seem to take some time, I'll say that now is the time to also add render hooks for titles.

So yes, just let me know when this is ready and I'll have a look and eventually merge it.

[apexskier]

I think this is close to ready:

• The main PR is https://github.com/gohugoio/hugo/pull/7133, which needs https://github.com/elihunter173/hugo/pull/1 merged (or https://github.com/gohugoio/hugo/commit/9186b4527258f7fa802644f6c2d7868d691b782b cherry-picked) into it.
• Docs PR is at https://github.com/gohugoio/hugoDocs/pull/1100
• And a PR to make hugo's theme use this is at https://github.com/gohugoio/gohugoioTheme/pull/146