链接渲染钩子

Markdown

一个 Markdown 链接有三个组成部分：链接文本、链接目标，以及可选的链接标题。

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

这些组成部分作为如下所示的渲染钩子上下文传入。

上下文

链接渲染钩子模板接收以下上下文

目标

（string）链接目标。

页面

（page）对当前页面的引用。

PageInner

（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 */ -}}

默认

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 详情

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 链接和图像目标。请参阅每个的源代码

• 嵌入式链接渲染钩子
• 嵌入式图像渲染钩子