ref 和 relref 简码

Hugo 默认提供了ref和 relref 简码：用于创建文档链接

简码：shortcodes

使用示例：

1
2
3
4
5
6
7
8
9

# 建议使用绝对路径（根目录为content目录），而非相对路径，否则容易出错
# 只有所引用的文件与当前文件在同一文件夹下时可以使用 相对路径的方式（只写文件名）
{{< ref "/posts/Tools/cmder.md" >}}
# 最后在 网页上显示：
https://www.thisfaner.com/p/cmder/

{{< relref "/posts/Tools/cmder.md" >}}
# 最后在 网页上显示：
/p/cmder/

直接在网页上显示 https://www.thisfaner.com/p/cmder/ 和 /p/cmder/，这并不是我们想要的。

一般的用法是，使用 []() 对其进行包裹：

1
2
3

[cmder]({{< ref "/posts/tools/cmder.md" >}})

[cmder]({{< relref "/posts/tools/cmder.md" >}})

最后生成的链接为：

• cmder
• cmder

官方示例：

1
2
3
4
5
6
7
8

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

ref 的单个参数是 本地目录中 带有内容文档名称（例如 about.md）的字符串，该字符串带有或不带有附加的文档内锚定位符（#who），不带空格。 Hugo 在我们搜索文档的方式上非常灵活，因此可以省略文件后缀。

没有前导/的路径将首先尝试相对于当前文件本地所在位置进行解析。

上面还演示了链接到文章中对应的锚点，比如 #anchor 。

错误

如果找不到文档或找到多个文档，您将得到一个错误。比如

Building sites … ERROR 2020/03/18 22:40:42 [zh] REF_NOT_FOUND:
Ref "/posts/tools/PowerShell主题设置.md":
"F:\Felix\Documents\Blog\hugoblog\content\posts\Tools\Cmder.md:415:28": page not found

常见的错误原因是：

在不能使用相对路径的情况，使用了相对路径，尽量使用 绝对路径引用本地文件。

另一个错误原因可能是你误将 路径 配置为 相对于最终生成的网页的 url 的路径；记住它是相对于本地文件目录来配置的。

配置 Ref 和 RelRef

自 Hugo 0.45 以来，该行为可以在 config.toml 中配置但 Ref 和 RelRef 出现错误时的处理方式：

refLinksErrorLevel（“ERROR”）：

当使用 ref 或 relref 解析页面链接而链接 无法解析时 ，将使用此日志级别记录该链接。有效值为 ERROR（默认值）或 WARNING 。

任何 ERROR 都将导致生成失败。

refLinksNotFoundURL：

在 ref 或 relref 中找不到页引用时用作占位符的 URL 。按原样使用。