Link render hooks

Create a link render hook to override the rendering of Markdown links to HTML.

Markdown

A Markdown link has three components: the link text, the link destination, and optionally the link title.

[Post 1](/posts/post-1 "My first post")
 ------  -------------  -------------
  text    destination       title

These components are passed into the render hook context as shown below.

Context

Link render hook templates receive the following context:

Destination: (string) The link destination.
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 link description as plain text.
Text: (template.HTML) The link description.
Title: (string) The link title.

Examples

With inline elements such as images and links, remove leading and trailing whitespace using the {{‑ ‑}} delimiter notation to prevent whitespace between adjacent inline elements and text.

In its default configuration, Hugo renders Markdown links according to the CommonMark specification. To create a render hook that does the same thing:

layouts/_default/_markup/render-link.html

<a href="{{ .Destination | safeURL }}"
  {{- with .Title }} title="{{ . }}"{{ end -}}
>
  {{- with .Text }}{{ . }}{{ end -}}
</a>
{{- /* chomp trailing newline */ -}}

To include a rel attribute set to external for external links:

layouts/_default/_markup/render-link.html

{{- $u := urls.Parse .Destination -}}
<a href="{{ .Destination | safeURL }}"
  {{- with .Title }} title="{{ . }}"{{ end -}}
  {{- if $u.IsAbs }} rel="external"{{ end -}}
>
  {{- with .Text }}{{ . }}{{ end -}}
</a>
{{- /* chomp trailing newline */ -}}

Default

New in v0.123.0

Hugo includes an embedded link render hook to resolve Markdown link destinations. Disabled by default, you can enable it in your site configuration:

markup:
  goldmark:
    renderHooks:
      link:
        enableDefault: true

[markup]
  [markup.goldmark]
    [markup.goldmark.renderHooks]
      [markup.goldmark.renderHooks.link]
        enableDefault = true

{
   "markup": {
      "goldmark": {
         "renderHooks": {
            "link": {
               "enableDefault": true
            }
         }
      }
   }
}

A custom render hook, even when provided by a theme or module, will override the embedded render hook regardless of the configuration setting above.

The embedded link render hook is automatically enabled for multilingual single-host sites if duplication of shared page resources is disabled. This is the default configuration for multilingual single-host sites.

The embedded link render hook resolves internal Markdown destinations by looking for a matching page, falling back to a matching page resource, then falling back to a matching global resource. Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination.

You must place global resources in the assets directory. If you have placed your resources in the static directory, and you are unable or unwilling to move them, you must mount the static directory to the assets directory by including both of these entries in your site configuration:

module:
  mounts:
  - source: assets
    target: assets
  - source: static
    target: assets

[module]
  [[module.mounts]]
    source = 'assets'
    target = 'assets'
  [[module.mounts]]
    source = 'static'
    target = 'assets'

{
   "module": {
      "mounts": [
         {
            "source": "assets",
            "target": "assets"
         },
         {
            "source": "static",
            "target": "assets"
         }
      ]
   }
}

PageInner details

New in v0.125.0

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:

layouts/shortcodes/include.html

{{ 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:

content/posts/p1.md

{{% 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.

The PageInner method is only relevant for shortcodes that invoke the RenderShortcodes method, and you must call the shortcode using Markdown notation.

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:

Last updated: March 8, 2025 : content: Replace note shortcode calls with blockquote alerts (c540e6d29)

Improve this page