Heading render hooks
Context
Heading render hook templates receive the following context:
- Anchor
- (
string
) Theid
attribute of the heading element. - Attributes
- (
map
) The Markdown attributes, available if you configure your site as follows:markup: goldmark: parser: attribute: title: true
[markup] [markup.goldmark] [markup.goldmark.parser] [markup.goldmark.parser.attribute] title = true
{ "markup": { "goldmark": { "parser": { "attribute": { "title": true } } } } }
- Level
- (
int
) The heading level, 1 through 6. - Page
- (
page
) A reference to the current page. - PageInner
- New in v0.125.0
- (
page
) A reference to a page nested via theRenderShortcodes
method. See details. - PlainText
- (
string
) The heading text as plain text. - Text
- (
template.HTML
) The heading text.
Examples
In its default configuration, Hugo renders Markdown headings according to the CommonMark specification with the addition of automatic id
attributes. To create a render hook that does the same thing:
<h{{ .Level }} id="{{ .Anchor }}" {{- with .Attributes.class }} class="{{ . }}" {{- end }}>
{{- .Text -}}
</h{{ .Level }}>
To add an anchor link to the right of each heading:
<h{{ .Level }} id="{{ .Anchor }}" {{- with .Attributes.class }} class="{{ . }}" {{- end }}>
{{ .Text }}
<a href="#{{ .Anchor }}">#</a>
</h{{ .Level }}>
PageInner details
New in v0.125.0The primary use case for PageInner
is to resolve links and page resources relative to an included Page
. For example, create an “include” shortcode to compose a page from multiple content files, while preserving a global context for footnotes and the table of contents:
{{ with .Get 0 }}
{{ with $.Page.GetPage . }}
{{- .RenderShortcodes }}
{{ else }}
{{ errorf "The %q shortcode was unable to find %q. See %s" $.Name . $.Position }}
{{ end }}
{{ else }}
{{ errorf "The %q shortcode requires a positional parameter indicating the logical path of the file to include. See %s" .Name .Position }}
{{ end }}
Then call the shortcode in your Markdown:
{{% include "/posts/p2" %}}
Any render hook triggered while rendering /posts/p2
will get:
/posts/p1
when callingPage
/posts/p2
when callingPageInner
PageInner
falls back to the value of Page
if not relevant, and always returns a value.
The PageInner
method is only relevant for shortcodes that invoke the RenderShortcodes
method, and you must call the shortcode using Markdown notation.
As a practical example, Hugo’s embedded link and image render hooks use the PageInner
method to resolve markdown link and image destinations. See the source code for each: