hugo/content/en/templates/render-hooks.md

title	linkTitle	description	date	categories	keywords	toc	menu
Markdown Render Hooks	Render Hooks	Render Hooks allow custom templates to override markdown rendering functionality.	2017-03-11	templates	markdown	true	docs title parent weight Markdown Render Hooks templates 20

{{< new-in "0.62.0" >}} Note that this is only supported with the Goldmark renderer.

You can override certain parts of the default Markdown rendering to HTML by creating templates with base names render-{kind} in layouts/_default/_markup.

You can also create type/section specific hooks in layouts/[type/section]/_markup, e.g.: layouts/blog/_markup.{{< new-in "0.71.0" >}}

The hook kinds currently supported are:

• image
• link
• heading {{< new-in "0.71.0" >}}
• codeblock{{< new-in "0.83.0" >}}

You can define Output-Format- and language-specific templates if needed. Your layouts folder may look like this:

layouts
└── _default
    └── _markup
        ├── render-image.html
        ├── render-image.rss.xml
        └── render-link.html
        └── render-codeblock.html
        └── render-codeblock-bash.html

Some use cases for the above:

• Resolve link references using .GetPage. This would make links portable as you could translate ./my-post.md (and similar constructs that would work on GitHub) into /blog/2019/01/01/my-post/ etc.
• Add target=_blank to external links.
• Resolve and process images.
• Add header links.

Render Hooks for Headings, Links and Images

The render-link and render-image templates will receive this context:

Page

The Page being rendered.

Destination

The URL.

Title

The title attribute.

Text

The rendered (HTML) link text.

PlainText

The plain variant of the above.

The render-heading template will receive this context:

Page

The Page being rendered.

Level

The header level (1--6)

Anchor

An auto-generated html id unique to the header within the page

Text

The rendered (HTML) text.

PlainText

The plain variant of the above.

Attributes (map) {{< new-in "0.82.0" >}}

A map of attributes (e.g. id, class)

Link with title Markdown example:

[Text](https://www.gohugo.io "Title")

Here is a code example for how the render-link.html template could look:

{{< code file="layouts/_default/_markup/render-link.html" >}} <a href="{{ .Destination | safeURL }}"{{ with .Title}} title="{{ . }}"{{ end }}{{ if strings.HasPrefix .Destination "http" }} target="_blank" rel="noopener"{{ end }}>{{ .Text | safeHTML }} {{< /code >}}

Image Markdown example:

![Text](https://d33wubrfki0l68.cloudfront.net/c38c7334cc3f23585738e40334284fddcaf03d5e/2e17c/images/hugo-logo-wide.svg "Title")

Here is a code example for how the render-image.html template could look:

{{< code file="layouts/_default/_markup/render-image.html" >}}

{{< /code >}}

Heading link example

Given this template file

{{< code file="layouts/_default/_markup/render-heading.html" >}} <h{{ .Level }} id="{{ .Anchor | safeURL }}">{{ .Text | safeHTML }} ¶</h{{ .Level }}> {{< /code >}}

And this markdown

### Section A

The rendered html will be

<h3 id="section-a">Section A <a href="#section-a">¶</a></h3>

Render Hooks for Code Blocks

{{< new-in "0.93.0" >}}

You can add a hook template for either all code blocks or for a specific type/language (bash in the example below):

layouts
└── _default
    └── _markup
        └── render-codeblock.html
        └── render-codeblock-bash.html

The default behaviour for these code blocks is to do Code Highlighting, but since you can pass attributes to these code blocks, they can be used for almost anything. One example would be the built-in GoAT Diagrams or this Mermaid Diagram Code Block Hook example.

The context (the ".") you receive in a code block template contains:

Type (string)

The type of code block. This will be the programming language, e.g. bash, when doing code highlighting.

Attributes (map)

Attributes passed in from Markdown (e.g. { attrName1=attrValue1 attrName2="attr Value 2" }).

Options (map)

Chroma highlighting processing options. This will only be filled if Type is a known Chroma Lexer.

Inner (string)

The text between the code fences.

Ordinal (integer)

Zero-based ordinal for all code blocks in the current document.

Page

The owning Page.

Position

Useful in error logging as it prints the filename and position (linenumber, column), e.g. {{ errorf "error in code block: %s" .Position }}.