短代码ref 和 relref用于相应地创建到达文档的绝对链接和相对链接.

使用 ref 和 relref

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{{< ref "document" >}}
{{< ref "document#anchor" >}}
{{< ref "document.md" >}}
{{< ref "document.md#anchor" >}}
{{< ref "#anchor" >}}
{{< ref "/blog/my-post" >}}
{{< ref "/blog/my-post.md" >}}
{{< relref "document" >}}
{{< relref "document.md" >}}
{{< relref "#anchor" >}}
{{< relref "/blog/my-post.md" >}}

在markdown中使用 ref 或者 relref 生成超链接:

1

[About]({{< ref "document/en/page/about" >}} "About Us")

短代码 ref and relref 需要一个参数: 到达内容文档的路径, 包含或者不包含文件扩展名，包含或者不包含页面锚点.

不包含开头 / 的路径首先会相对于当前页面解析，然后相对于整个站点其余部分解析.

如果文档无法被唯一解析，Hugo会生成错误. 错误行为可以配置，参见下面.

链接到另一语言版本

链接到文档的另一个语言的版本，使用这样格式:

1

{{< relref path="document.md" lang="ja" >}}

获得另一种输出模式

链接到文档的另一种输出格式, 格式如下:

1

{{< relref path="document.md" outputFormat="rss" >}}

标题ID

使用Markdown文档类型时,hugo会为页面上每个heading生成元素的IDs. 例如:

1

## Reference

生成如下HTML:

1

<h2 id="reference">Reference</h2>

使用ref or relref时在路径后面附加这个ID可以获得到达页面标题的链接:

1
2

{{< ref "document.md#reference" >}}
{{< relref "document.md#reference" >}}

生成包换属性的定制头部ID, 比如:

1
2

## Reference A {#foo}
## Reference B {id="bar"}

produces this HTML:

1
2

<h2 id="foo">Reference A</h2>
<h2 id="bar">Reference B</h2>

如果相同的标题在同一页面上出现多次, Hugo会生成独特的元素ID. 例如:

1
2
3

## Reference
## Reference
## Reference

生成HTML如下:

1
2
3

<h2 id="reference">Reference</h2>
<h2 id="reference-1">Reference</h2>
<h2 id="reference-2">Reference</h2>

Ref 和 RelRef 的配置

从HUgo0.45版本开始,ref和relref的行为可以通过配置文件 config.toml配置:

refLinksErrorLevel (“ERROR”) :使用ref 或者 relref解析页面链接时, 如果链接无法解析，日志记录的log级别。有效值是 ERROR (缺省值) 或者 WARNING. 任何 ERROR 将导致hugo构建过程失败(exit -1)

refLinksNotFoundURL
使用ref 或者 relref解析页面链接时, 如果链接无法找到，使用这个URL作为占位符. 按原样使用.