RelRef
返回具有给定路径、语言和输出格式的页面的相对 URL。
这一页解决什么问题
.RelRef 与 .Ref 完全同源:用逻辑路径解析目标页面,区别只在返回相对 URL(/posts/post-1/)。模板里写站内链接时,它比手写路径安全——目标页面被改名或删除时,构建会直接报错,而不是留下 404。
什么时候用,什么时候别用
该用:
- 模板里生成站内链接,特别是路径由变量拼出、或目标可能被挪动时;
- 需要按语言取对等页面(
lang选项); - 需要在链接上附加自定义属性/文案时先拿到 URL。
别用:
- 需要绝对 URL(RSS、
og:url)→ 用.Ref; - 已经有目标页面的
Page对象 → 直接用.RelPermalink; - 在内容 Markdown 里做链接 → 用
ref/relref短代码(它们最终也走同一套解析)。
选哪个:
| 需求 | 用哪个 |
|---|---|
| 站内相对链接 | .RelRef |
| 绝对 URL | .Ref |
手上是 Page 对象 |
.RelPermalink / .Permalink |
| Markdown 正文里写链接 | relref / ref 短代码 |
用法
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 无法解析该路径,它会抛出错误并导致构建失败。你可以在项目配置中把它改为警告,并指定无法解析路径时要返回的 URL。
toml
refLinksErrorLevel = 'warning'
refLinksNotFoundURL = '/some/other/url'完整示例:生成站内链接
模板(layouts/_default/single.html):
layouts/_default/single.htmlgo-html-template
<a href="{{ .RelRef (dict "path" "/posts/post-2") }}">相关阅读</a>
<a href="{{ .RelRef (dict "path" "/posts/post-1" "lang" "zh") }}">中文版</a>在 /posts/post-2/ 上实测(Hugo 0.167.0,baseURL = 'https://example.org/'):
html
<a href="/posts/post-2/">相关阅读</a>
<a href="/zh/posts/post-1/">中文版</a>把同一次构建改成 --baseURL 'https://example.org/docs/' 后,实测输出为:
html
<a href="/docs/posts/post-2/">相关阅读</a>
<a href="/docs/zh/posts/post-1/">中文版</a>你应当看到什么:与 .RelPermalink 一样,返回值会带上 baseURL 的子路径(/docs)与语言段(/zh),所以把站点搬进子目录、或多语言切换时都不需要改模板。
返回值边界(实测)
| 情况 | 结果 | 是否报错 |
|---|---|---|
path 指向存在的页面 |
相对 URL(实测 /posts/post-2/) |
否 |
path 不带前导斜杠 |
先相对当前页面解析(实测 post-1 命中 /posts/post-1,输出用其 slug URL) |
否 |
lang 指向另一语言 |
返回该语言版本的相对 URL(实测 /zh/posts/post-1/) |
否 |
baseURL 带子路径 |
结果包含子路径(实测 /docs/posts/post-2/) |
否 |
path 不存在 |
—— | 是:REF_NOT_FOUND … page not found,构建退出码 1;可用 refLinksErrorLevel = 'warning' 降级 |
| 返回类型 | string(相对 URL,以 / 开头) |
否 |
更多排查入口见故障排查。