Shortcode

RelRef

返回具有给定路径、语言和输出格式的页面的相对 URL。

签名
SHORTCODE.RelRef OPTIONS
返回类型
string

这一页解决什么问题

RelRef 把「页面路径」解析成根相对 URL(如 /posts/post-1/),解析失败则让构建失败。它是站内链接的正确来源:相对路径在本地预览、子路径部署、更换域名时都不需要改动,而写错的路径会在构建时就被拦下。

与 Ref 只差一点:Ref 给绝对 URL(带域名),RelRef 给相对 URL。站内一律用 RelRef。

什么时候用,什么时候别用

该用:

  • 任何站内链接:导航、正文里的交叉引用、卡片、列表;
  • 需要在构建阶段校验目标页面存在;
  • 需要链接到另一种输出格式的同一页面(如 .json)。

别用:

  • 站外链接 → 直接写 URL;
  • 需要绝对 URL(RSS/Atom、结构化数据、邮件)→ 用 Ref 或 Permalink;
  • 在内容文件里写站内链接:那里用 Markdown 链接,或 relref 短代码(写法见下文),不必在模板里调方法;
  • 指向资源文件(图片/附件)→ 用 RelPermalink。

用法

RelRef 方法需要单个参数:一个选项映射。

选项

path
(string)目标页面的路径。不以斜杠(/)开头的路径先相对于当前页面解析,再相对于站点的其余部分解析。
lang
(string)目标页面的语言。默认是当前语言。可选。
outputFormat
(string)目标页面的输出格式。默认是当前输出格式。可选。

示例

下面的示例展示了站点英文版本中某个页面的渲染输出:

go-html-template
{{ $opts := dict "path" "/books/book-1" }}
{{ .RelRef $opts }} → /en/books/book-1/

{{ $opts := dict "path" "/books/book-1" "lang" "de" }}
{{ .RelRef $opts }} → /de/books/book-1/

{{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }}
{{ .RelRef $opts }} → /de/books/book-1/index.json

完整示例(实测)

测量条件:Hugo 0.167.0 extended,Windows,单语言最小站点,目标页面 content/posts/post-1.md 存在。

模板 layouts/_shortcodes/refs-demo.html:

layouts/_shortcodes/refs-demo.htmlgo-html-template
<a href="{{ .RelRef (dict "path" "/posts/post-1") }}">用绝对路径</a>
<a href="{{ .RelRef (dict "path" "posts/post-1") }}">用相对路径</a>
<a href="{{ .RelRef (dict "path" "posts/post-1.md") }}">带扩展名</a>
<a href="{{ .Ref (dict "path" "/posts/post-1") }}">对照:Ref</a>

内容 content/about.md:

content/about.mdmd
{{< refs-demo >}}

Hugo 渲染为(实测):

html
<a href="/posts/post-1/">用绝对路径</a>
<a href="/posts/post-1/">用相对路径</a>
<a href="/posts/post-1/">带扩展名</a>
<a href="https://example.org/posts/post-1/">对照:Ref</a>

你应当看到什么:四种写法都解析到了同一个页面——前三个 href 都是根相对的 /posts/post-1/,最后一个(Ref)带上了域名。单语言站点的路径里没有语言段(多语言站点会带上,如上游示例的 /en/books/book-1/)。

如果你在内容文件里而不是模板里写站内链接,用的是 relref 短代码(与本方法同名、同源):

content/about.mdmd
[第一篇](/posts/post-1/)
见 {{< relref "posts/post-1.md" >}}

错误处理

默认情况下,如果 Hugo 无法解析路径,它会抛出错误并让构建失败。你可以在项目配置中把它改成警告,并指定无法解析路径时要返回的 URL。

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

返回值边界(实测)

情况 结果 是否报错
存在的页面 根相对 URL(单语言实测 /posts/post-1/) 否
path 不以 / 开头 先相对当前页面解析(实测得到同一 URL) 否
path 带 .md 扩展名 同样能解析 否
页面不存在 记录 REF_NOT_FOUND 是:构建失败(默认 refLinksErrorLevel = 'error')
lang 指向不存在的语言 记录 REF_NOT_FOUND: … no site found with lang "de" 是:构建失败
outputFormat 指向未启用的格式 记录 REF_NOT_FOUND: … output format "json" 是:构建失败
用 try 包住 接不住(属于站点构建错误) 是:构建失败

常见坑

类别 症状 真因 怎么修
没报错但结果不对 站内链接带上了域名 用了 Ref 站内改用 RelRef
构建失败 REF_NOT_FOUND: … page not found 路径写错,或目标页面不参与构建 核对路径;检查 draft 与 build 选项
没报错但结果不对 多语言站点里链接跳到了错误语言 依赖默认 lang 显式传 dict "path" … "lang" …
没报错但结果不对 内容里写了 {{< relref >}} 却报短代码不存在 该站点/版本未启用 relref 短代码,或写法有误 用 Markdown 链接,或改在模板里用 .RelRef

更多排查入口见故障排查。