Code block render hooks

Markdown

This Markdown example contains a fenced code block:

```bash {class="my-class" id="my-codeblock" lineNos=inline tabWidth=2}
declare a=1
echo "$a"
exit
```

A fenced code block consists of:

• A leading code fence
• An optional info string
• A code sample
• A trailing code fence

In the previous example, the info string contains:

• The language of the code sample (the first word)
• An optional space-delimited or comma-delimited list of attributes (everything within braces)

The attributes in the info string can be generic attributes or highlighting options.

In the example above, the generic attributes are class and id. In the absence of special handling within a code block render hook, Hugo adds each generic attribute to the HTML element surrounding the rendered code block. Consistent with its content security model, Hugo removes HTML event attributes such as onclick and onmouseover. Generic attributes are typically global HTML attributes, but you may include custom attributes as well.

In the example above, the highlighting options are lineNos and tabWidth. Hugo uses the Chroma syntax highlighter to render the code sample. You can control the appearance of the rendered code by specifying one or more highlighting options.

Context

Code block render hook templates receive the following context:

Attributes

(map) The generic attributes from the info string.

Inner

(string) The content between the leading and trailing code fences, excluding the info string.

Options

(map) The highlighting options from the info string.

Ordinal

(int) The zero-based ordinal of the code block on the page.

Page

(page) A reference to the current page.

PageInner

(page) A reference to a page nested via the RenderShortcodes method. See details.

Position

(text.Position) The position of the code block within the page content.

Type

(string) The first word of the info string, typically the code language.

Examples

In its default configuration, Hugo renders fenced code blocks by passing the code sample through the Chroma syntax highlighter and wrapping the result. To create a render hook that does the same thing:

{{ $result := transform.HighlightCodeBlock . }}
{{ $result.Wrapped }}

Although you can use one template with conditional logic to control the behavior on a per-language basis, you can also create language-specific templates.

layouts/
└── _default/
    └── _markup/
        ├── render-codeblock-mermaid.html
        ├── render-codeblock-python.html
        └── render-codeblock.html

For example, to create a code block render hook to render Mermaid diagrams:

<pre class="mermaid">
  {{- .Inner | htmlEscape | safeHTML }}
</pre>
{{ .Page.Store.Set "hasMermaid" true }}

Then include this snippet at the bottom of the your base template:

{{ if .Store.Get "hasMermaid" }}
  <script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
  </script>
{{ end }}

See the diagrams page for details.

Embedded

Hugo includes an embedded code block render hook to render GoAT diagrams.

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/p2" %}}

Any render hook triggered while rendering /posts/p2 will get:

• /posts/p1 when calling Page
• /posts/p2 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