HUGO

  • News
  • Docs
  • Themes
  • Showcase
  • Community
  • GitHub
gohugoio Star
  • About Hugo
    • Overview
    • What is Hugo
    • Hugo features
    • Static site generators
    • Hugo's security model
    • Hugo and the GDPR
    • License
  • Installation
    • Overview
    • macOS
    • Linux
    • Windows
    • BSD
  • Getting started
    • Overview
    • Quick start
    • Basic usage
    • Directory structure
    • Configuration
    • Configure markup
    • Glossary of terms
    • External learning resources
  • Content management
    • Overview
    • Organization
    • Page bundles
    • Content formats
    • Diagrams
    • Front matter
    • Build options
    • Page resources
    • Image processing
    • Shortcodes
    • Related content
    • Sections
    • Content types
    • Archetypes
    • Taxonomies
    • Summaries
    • Links and cross references
    • URL management
    • Menus
    • Static files
    • Table of contents
    • Comments
    • Multilingual
    • Syntax highlighting
  • Templates
    • Overview
    • Templating
    • Template lookup order
    • Base templates and blocks
    • Single page templates
    • List templates
    • Homepage template
    • Section templates
    • Taxonomy templates
    • Pagination
    • Content view templates
    • Partial templates
    • Shortcode templates
    • Menu templates
    • Data templates
    • RSS templates
    • Sitemap templates
    • Local file templates
    • Internal templates
    • Render hooks
    • Custom output formats
    • 404 page
    • Robots.txt
  • Functions
    • Overview
    • cast
    • collections
    • compare
    • crypto
    • data
    • debug
    • diagrams
    • encoding
    • fmt
    • global
    • go template
    • hugo
    • images
    • inflect
    • js
    • lang
    • math
    • openapi3
    • os
    • partials
    • path
    • reflect
    • resources
    • safe
    • strings
    • templates
    • time
    • transform
    • urls
  • Methods
    • Overview
    • Duration
    • Menu
    • Menu entry
    • Page
    • Pages
    • Resource
    • Shortcode
    • Site
    • Taxonomy
    • Time
  • Quick reference
    • Overview
    • Emojis
    • Functions
    • Methods
    • Page collections
  • Variables
    • Overview
    • File variables
    • Git variables
    • Menu entry variables
    • Page variables
    • Pages variables
    • Shortcode variables
    • Site variables
    • Taxonomy variables
  • Hugo Modules
    • Overview
    • Configure Hugo modules
    • Use Hugo Modules
    • Theme components
  • Hugo Pipes
    • Overview
    • Introduction
    • Transpile Sass to CSS
    • PostCSS
    • PostProcess
    • JavaScript building
    • Babel
    • Asset minification
    • Concatenating assets
    • Fingerprinting and SRI hashing
    • Resource from string
    • Resource from template
  • CLI
  • Troubleshooting
    • Overview
    • Audit
    • Logging
    • Inspection
    • Deprecation
    • Performance
    • FAQs
  • Developer tools
    • Overview
    • Editor plugins
    • Front-ends
    • Search
    • Migrations
    • Other projects
  • Hosting and deployment
    • Overview
    • Hugo Deploy
    • Deploy with Rclone
    • Deploy with Rsync
    • Host on 21YunBox
    • Host on AWS Amplify
    • Host on Azure Static Web Apps
    • Host on Cloudflare Pages
    • Host on Firebase
    • Host on GitHub Pages
    • Host on GitLab Pages
    • Host on KeyCDN
    • Host on Netlify
    • Host on Render
  • Contribute
    • Overview
    • Development
    • Documentation
    • Themes
  • Maintenance
TEMPLATES

Markdown render hooks

Render Hooks allow custom templates to override markdown rendering functionality.

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:

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 }}</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:

layouts/_default/_markup/render-image.html
<p class="md__image">
  <img src="{{ .Destination | safeURL }}" alt="{{ .Text }}" {{ with .Title }} title="{{ . }}"{{ end }} />
</p>

Heading link example

Given this template file

layouts/_default/_markup/render-heading.html
<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):

l└a─y─ou_└td─se─fa_└└um──la──trkrrueepnnddeerr--ccooddeebblloocckk.-hbtamslh.html

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 }}.

See also

  • Content formats
  • Shortcodes

On this page

  • Render hooks for headings, links and images
  • Render hooks for code blocks
Last updated: November 11, 2023: Add methods deprecated in v0.120.0 (0f0ab2ad)
Improve this page
By the Hugo Authors
Hugo Logo
  • File an Issue
  • Get Help
  • @GoHugoIO
  • @spf13
  • @bepsays

Netlify badge

 

Hugo Sponsors

 

The Hugo logos are copyright © Steve Francia 2013–2023.

The Hugo Gopher is based on an original work by Renée French.

  • News
  • Docs
  • Themes
  • Showcase
  • Community
  • GitHub
  • About Hugo
  • Installation
  • Getting started
  • Content management
  • Templates
  • Functions
  • Methods
  • Quick reference
  • Variables
  • Hugo Modules
  • Hugo Pipes
  • CLI
  • Troubleshooting
  • Developer tools
  • Hosting and deployment
  • Contribute
  • Maintenance