Heading render hooks

Context

Heading render hook templates receive the following context:

Anchor

(string) The id 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 the RenderShortcodes 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

The 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/post-2" %}}

Any render hook triggered while rendering /posts/post-2 will get:

• /posts/post-1 when calling Page
• /posts/post-2 when calling PageInner

PageInner falls back to the value of Page if not relevant, and always returns a value.

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:

• Embedded link render hook
• Embedded image render hook