Markdown render hooks
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
.
The hook kinds currently supported are:
image
link
heading
codeblock
You can define Output-Format- and language-specific templates if needed. Your layouts
folder may look like this:
layouts/
└── _default/
└── _markup/
├── render-codeblock-bash.html
├── render-codeblock.html
├── render-heading.html
├── render-image.html
├── render-image.rss.xml
└── render-link.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
Context passed to render-link
and render-image
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.
Context passed to render-heading
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)
- A map of attributes (e.g.
id
,class
). Note that this will currently always be empty for links.
The render-image
templates will also receive:
- IsBlock
- Returns true if this is a standalone image and the configuration option markup.goldmark.parser.wrapStandAloneImageWithinParagraph is disabled.
- Ordinal
- Zero-based ordinal for all the images in the current document.
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:
<a href="{{ .Destination | safeURL }}"{{ with .Title }} title="{{ . }}"{{ end }}{{ if strings.HasPrefix .Destination "http" }} target="_blank" rel="noopener"{{ end }}>{{ .Text | safeHTML }}</a>
Image markdown example
![Text](https://gohugo.io/images/hugo-logo-wide.svg "Title")
Here is a code example for how the render-image.html template could look:
<p class="md__image">
<img src="{{ .Destination | safeURL }}" alt="{{ .Text }}" {{ with .Title }} title="{{ . }}"{{ end }} />
</p>
Heading link example
Given this template file
<h{{ .Level }} id="{{ .Anchor | safeURL }}">{{ .Text | safeHTML }} <a href="#{{ .Anchor | safeURL }}">¶</a></h{{ .Level }}>
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
You can add a hook template for either all code blocks or for a specific type/language (bash
in the example below):
The default behavior 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 file name and position (linenumber, column), e.g.
{{ errorf "error in code block: %s" .Position }}
.