Hugo Ref 短代码

使用 ref 短代码插入给定页面引用的永久链接。

要覆盖 Hugo 内置的 ref 短代码，请将源代码复制到 layouts/_shortcodes 目录中同名文件中。

使用 Markdown 时，此短代码已过时。相反，要正确解析 Markdown 链接目标，请使用嵌入式链接渲染钩子或创建你自己的。

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

你还可以配置 Hugo always 使用嵌入式链接渲染钩子、仅作为 fallback 使用，或 never 使用。详见配置说明。

用法

ref 短代码接受单个位置参数（路径）或一个或多个命名参数，如下所列。

参数

path: (string) 目标页面的路径。没有前导斜杠 (/) 的路径首先相对于当前页面解析，然后相对于站点其余部分解析。
lang: (string) 目标页面的语言。默认为当前语言。可选。
outputFormat: (string) 目标页面的输出格式。默认为当前输出格式。可选。

示例

ref 短代码通常为 Markdown 链接提供目标。

调用此短代码时始终使用 Markdown 标记法。

以下示例显示站点英文版本页面上的渲染输出：

[链接 A]({{% ref "/books/book-1" %}})

[链接 B]({{% ref path="/books/book-1" %}})

[链接 C]({{% ref path="/books/book-1" lang="de" %}})

[链接 D]({{% ref path="/books/book-1" lang="de" outputFormat="json" %}})

渲染后：

<a href="https://example.org/en/books/book-1/">链接 A</a>

<a href="https://example.org/en/books/book-1/">链接 B</a>

<a href="https://example.org/de/books/book-1/">链接 C</a>

<a href="https://example.org/de/books/book-1/index.json">链接 D</a>

错误处理

默认情况下，如果 Hugo 无法解析路径，它将抛出错误并使构建失败。您可以在站点配置中将其更改为警告，并指定在无法解析路径时返回的 URL。

refLinksErrorLevel: warning
refLinksNotFoundURL: /some/other/url

refLinksErrorLevel = 'warning'
refLinksNotFoundURL = '/some/other/url'

{
   "refLinksErrorLevel": "warning",
   "refLinksNotFoundURL": "/some/other/url"
}

Last updated: January 1, 0001

Improve this page