relref

用法

relref 短代码接受单个位置参数（路径），或者一个或多个命名参数，见下表。

参数

path

（string）目标页面的路径。不以斜杠（/）开头的路径先相对当前页面解析，再相对站点其余部分解析。

lang

（string）目标页面的语言。默认为当前语言。可选。

outputFormat

（string）目标页面的输出格式。默认为当前输出格式。可选。

示例

relref 短代码的典型用途是为 Markdown 链接提供目标地址。

下面的例子给出站点英文版页面上的渲染结果：

[Link A]({{% relref "/books/book-1" %}})

[Link B]({{% relref path="/books/book-1" %}})

[Link C]({{% relref path="/books/book-1" lang="de" %}})

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

渲染结果：

<a href="/en/books/book-1/">Link A</a>

<a href="/en/books/book-1/">Link B</a>

<a href="/de/books/book-1/">Link C</a>

<a href="/de/books/book-1/index.json">Link D</a>

ref 与 relref 的差别

两个短代码接受的参数完全相同，解析路径的方式也相同，区别只在输出的地址形式：ref 输出包含站点地址的永久链接（permanent link），relref 输出相对于站点根目录的地址（relative permalink）。前者适合需要绝对地址的场合，例如站点摘要或外部引用；后者不写死域名，便于在测试环境与生产环境之间迁移。

错误处理

默认情况下，Hugo 无法解析路径时会抛出错误并让构建失败。可以在项目配置中改为警告，并指定无法解析路径时返回的地址：

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