relref
用 relref 短代码插入相对永久链接:与 ref 的唯一差别、必须用 Markdown 记法的原因、参数表与报错处理。
开始之前,你需要
- 站点能构建成功(
hugo --renderToMemory退出码为 0)。 - 读过 ref——本页只讲差别,其余规则完全相同。
读完之后你能
- 说出
ref与relref输出地址的唯一差别,并判断自己的场景该用哪一个; - 用
relref写出站内链接,并在产物里核对它确实是根相对地址; - 知道什么时候
relref反而不合适(需要绝对地址的场合,例如 RSS 与外部引用)。
这一页解决什么问题
站内互链最怕写死域名:https://example.org/posts/my-post/ 这种地址一旦站点换域名、或者要在本地预览与生产环境之间来回切换,就得全站替换。
relref 短代码把「路径」交给 Hugo 去查,但输出不含站点地址的根相对地址(relative permalink),例如 /posts/my-post/。页面搬到哪个域名下都能用,这也正是它与 ref 的唯一差别。
用法
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>地址里没有 https://example.org——这就是 relref。
为什么必须用 Markdown 记法
与 ref 同理:relref 的输出要落在 Markdown 链接的目标地址位置上,而目标地址由 Markdown 渲染器解析,所以短代码必须在 Markdown 渲染之前完成,也就是用 % 定界符。
实测(Hugo 0.167):[Link]({{% relref "/books/book-1" %}}) 渲染为 <a href="/books/book-1/">Link</a>;改用标准记法时,上游文档说 href 会被解析成空值——但本站复现不出来,两种记法都得到了填好地址的链接(原因与更正见 ref 一页)。短代码单独成行时两种记法都能用,但 Markdown 记法的输出会被渲染器自动包成链接,标准记法输出纯文本(relref 给的是根相对地址,不会被自动链接,两者都不产生链接)。
ref 与 relref 的差别
两个短代码接受的参数完全相同,解析路径的方式也相同,区别只在输出的地址形式:ref 输出包含站点地址的永久链接(permanent link),relref 输出相对于站点根目录的地址(relative permalink)。前者适合需要绝对地址的场合,例如站点摘要或外部引用;后者不写死域名,便于在测试环境与生产环境之间迁移。
实测(Hugo 0.167)同一个路径的输出对照:
| 调用 | 输出 |
|---|---|
{{< ref "/books/book-1" >}} |
https://example.org/en/books/book-1/ |
{{< relref "/books/book-1" >}} |
/en/books/book-1/ |
本站实际渲染效果
同一个地址,两个短代码输出什么,一眼可见(都是本站的真实输出):
看看 figure 那一页——地址不带域名,换域名不用改。
单独成行时:
relref的输出:/shortcodes/figure/ref的输出:https://hugozh.cn/shortcodes/figure/
relref 给的是根相对地址,因此即便用 Markdown 记法单独成行,也不会被 Markdown 渲染器自动包成链接(自动链接只认 http/https 开头的裸网址);ref 给的是完整网址,单独成行时会被自动包成链接。两个值分别贴进浏览器地址栏,打开的是同一页。
错误处理
默认情况下,Hugo 无法解析路径时会抛出错误并让构建失败。可以在项目配置中改为警告,并指定无法解析路径时返回的地址:
refLinksErrorLevel = 'warning'
refLinksNotFoundURL = '/some/other/url'relref 与 ref 共用这两个配置项。实测(Hugo 0.167):把 refLinksErrorLevel 设为 'warning' 并设置 refLinksNotFoundURL 后,路径不存在时构建只打印
WARN [en] REF_NOT_FOUND: Ref "/books/nope": "…/content/example.md:26:1": page not found并把地址替换成 refLinksNotFoundURL 的值;警告里的 文件:行:列 直接指向出问题的调用。只改级别而不设 refLinksNotFoundURL 会产生空 href,构建是绿的但链接全废,生产环境建议保留默认的 ERROR。
什么时候用,什么时候别用
该用:
- 正文里的站内互链,希望地址与域名解耦;
- 本地开发、预览环境与生产环境共用同一份内容;
- 需要链接到另一个语言版本(
lang)或非 HTML 输出格式(outputFormat)。
别用:
验证方法
-
在内容里写一次调用:
content/example.mdmd参见 [另一篇文章]({{% relref "/posts/my-post" %}})。 -
构建并查看产物:
bashhugo -
打开
public/example/index.html,搜索my-post。
你应当看到什么:<a href="/posts/my-post/">另一篇文章</a>——以 / 开头、没有域名。
- 如果
href里带了https://…,说明你用的是ref; - 如果
href为空,检查是不是用了标准记法,或路径写错; - 如果构建失败并提示
REF_NOT_FOUND,按报错里的文件:行:列去改路径。
常见坑
| 类别 | 现象 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | 链接点不动,href="" |
用标准记法调用,且短代码嵌在 Markdown 链接的目标地址里 | 改用 Markdown 记法(% 定界符) |
| 没报错但结果不对 | RSS 或第三方摘要里的链接打不开 | 那里需要绝对地址,relref 给的是根相对地址 |
在这些场合改用 ref |
| 没报错但结果不对 | 本地预览正常、部署后 404 | 站点部署在子路径下,而根相对地址是按 baseURL 的路径前缀生成的 |
确认 baseURL 与实际部署路径一致 |
| 报错看不懂 | REF_NOT_FOUND |
路径不存在;不以 / 开头的路径先相对当前页面解析,容易基准不对 |
用根相对路径(以 / 开头)最稳妥 |
| 报错看不懂 | 警告里出现你没想到的语言(如 [de]) |
lang 指向的语言里没有该页面或其输出格式 |
确认目标语言里确实有这一页 |
| 报错看不懂 | 构建成功但线上是旧链接 | 改了 URL 结构却没重新构建,或部署了旧的 public/ |
重新构建并检查部署目录 |
更多排查入口见故障排查。