链接渲染钩子

Markdown

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

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

这些组件会传递到渲染钩子 上下文 中，如下所示。

上下文

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

Destination

(string) 链接目标。

Page

(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>
{{- /* 删除尾随换行符 */ -}}

要为外部链接添加设置为 external 的 rel 属性：

{{- $u := urls.Parse .Destination -}}
<a href="{{ .Destination | safeURL }}"
  {{- with .Title }} title="{{ . }}"{{ end -}}
  {{- if $u.IsAbs }} rel="external"{{ end -}}
>
  {{- with .Text }}{{ . }}{{ end -}}
</a>
{{- /* 删除尾随换行符 */ -}}

嵌入式

Hugo 包含一个 嵌入式链接渲染钩子 来解析 Markdown 链接目标。您可以在站点配置中调整其行为。这是默认设置：

markup:
  goldmark:
    renderHooks:
      link:
        useEmbedded: auto

[markup]
  [markup.goldmark]
    [markup.goldmark.renderHooks]
      [markup.goldmark.renderHooks.link]
        useEmbedded = 'auto'

{
   "markup": {
      "goldmark": {
         "renderHooks": {
            "link": {
               "useEmbedded": "auto"
            }
         }
      }
   }
}

如上所示设置为 auto 时，Hugo 会自动为多语言单主机站点使用嵌入式链接渲染钩子，特别是在 共享页面资源复制 功能被禁用时。这是此类站点的默认行为。如果您的项目、模块或主题定义了自定义链接渲染钩子，则会使用这些钩子。

您还可以配置 Hugo always（始终）使用嵌入式链接渲染钩子、仅作为 fallback（后备）使用，或 never（从不）使用。请参阅 详情。

嵌入式链接渲染钩子通过查找匹配的页面来解析内部 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 "短代码 %q 无法找到 %q。参见 %s" $.Name . $.Position }}
  {{ end }}
{{ else }}
  {{ errorf "短代码 %q 需要一个位置参数来指示要包含的文件的逻辑路径。参见 %s" .Name .Position }}
{{ end }}

然后在您的 Markdown 中调用短代码：

{{% include "/posts/post-2" %}}

在渲染 /posts/post-2 时触发的任何渲染钩子将获得：

• 调用 Page 时获得 /posts/post-1
• 调用 PageInner 时获得 /posts/post-2

如果不相关，PageInner 会回退到 Page 的值，并且始终返回一个值。

作为实际示例，Hugo 的嵌入式链接和图像渲染钩子使用 PageInner 方法来解析 Markdown 链接和图像目标。请参阅各自的源代码：

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