链接渲染钩子
Markdown
一个 Markdown 链接有三个组成部分:链接文本、链接目标,以及可选的链接标题。
[Post 1](/posts/post-1 "My first post")
------ ------------- -------------
text destination title
这些组成部分作为如下所示的渲染钩子上下文传入。
上下文
链接渲染钩子模板接收以下上下文
目标
(string
)链接目标。
页面
(page
)对当前页面的引用。
PageInner
v0.125.0 中的新增功能(page
)通过 RenderShortcodes
方法嵌套的页面的引用。查看详情。
PlainText
(string
)链接描述的纯文本。
Text
(template.HTML
)链接描述。
Title
(string
)链接标题。
示例
在其默认配置中,Hugo 根据CommonMark 规范渲染 Markdown 链接。要创建一个执行相同操作的渲染钩子
<a href="{{ .Destination | safeURL }}"
{{- with .Title }} title="{{ . }}"{{ end -}}
>
{{- with .Text }}{{ . }}{{ end -}}
</a>
{{- /* chomp trailing newline */ -}}
要为外部链接包含一个设置为 external
的 rel
属性
{{- $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 */ -}}
默认
v0.123.0 中的新增功能Hugo 包含一个嵌入式链接渲染钩子来解析 Markdown 链接目标。默认情况下禁用,您可以在站点配置中启用它
markup:
goldmark:
renderHooks:
link:
enableDefault: true
[markup]
[markup.goldmark]
[markup.goldmark.renderHooks]
[markup.goldmark.renderHooks.link]
enableDefault = true
{
"markup": {
"goldmark": {
"renderHooks": {
"link": {
"enableDefault": true
}
}
}
}
}
自定义渲染钩子,即使由主题或模块提供,也会覆盖嵌入式渲染钩子,而不管上述配置设置如何。
嵌入式链接渲染钩子通过查找匹配的页面来解析内部 Markdown 目标,回退到匹配的页面资源,然后回退到匹配的全局资源。远程目标将直接传递,如果无法解析目标,渲染钩子不会引发错误或警告。
您必须将全局资源放置在 assets
目录中。如果您已将资源放置在 static
目录中,并且您无法或不愿移动它们,您必须通过在您的站点配置中包含以下两个条目,将 static
目录挂载到 assets
目录。
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 详情
v0.125.0 中的新增功能PageInner
的主要用例是解析相对于包含的 Page
的链接和 页面资源。例如,创建一个 “include” 短代码,从多个内容文件组成一个页面,同时为脚注和目录保留全局上下文。
{{ 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 }}
然后在您的 Markdown 中调用此短代码
{{% include "/posts/p2" %}}
在渲染 /posts/p2
时触发的任何渲染钩子都将获得
- 调用
Page
时获得/posts/p1
- 调用
PageInner
时获得/posts/p2
如果 PageInner
不相关,则会回退到 Page
的值,并且始终返回一个值。
作为一个实际示例,Hugo 的嵌入式链接和图像渲染钩子使用 PageInner
方法来解析 Markdown 链接和图像目标。请参阅每个的源代码