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 #
(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 #
In its default configuration, Hugo renders Markdown links according to the [CommonMark specification]. To create a render hook that does the same thing:
<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:
{{- $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 #
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 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"
}
]
}
}