短代码

relref

用 relref 短代码插入相对永久链接:与 ref 的唯一差别、必须用 Markdown 记法的原因、参数表与报错处理。

难度
入门
预计用时
8 分钟

开始之前,你需要

  • 站点能构建成功(hugo --renderToMemory 退出码为 0)。
  • 读过 ref——本页只讲差别,其余规则完全相同。

读完之后你能

  • 说出 ref 与 relref 输出地址的唯一差别,并判断自己的场景该用哪一个;
  • 用 relref 写出站内链接,并在产物里核对它确实是根相对地址;
  • 知道什么时候 relref 反而不合适(需要绝对地址的场合,例如 RSS 与外部引用)。

接着读:ref · 链接

这一页解决什么问题

站内互链最怕写死域名:https://example.org/posts/my-post/ 这种地址一旦站点换域名、或者要在本地预览与生产环境之间来回切换,就得全站替换。

relref 短代码把「路径」交给 Hugo 去查,但输出不含站点地址的根相对地址(relative permalink),例如 /posts/my-post/。页面搬到哪个域名下都能用,这也正是它与 ref 的唯一差别。

用法

relref 短代码接受单个位置参数(路径),或者一个或多个命名参数,见下表。

参数

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

示例

relref 短代码的典型用途是为 Markdown 链接提供目标地址。

下面的例子给出站点英文版页面上的渲染结果:

md
[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" %}})

渲染结果:

html
<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/

本站实际渲染效果

同一个地址,两个短代码输出什么,一眼可见(都是本站的真实输出):

relref:给 HTML 链接填地址

看看 figure 那一页——地址不带域名,换域名不用改。

单独成行时:

  • relref 的输出:/shortcodes/figure/
  • ref 的输出:https://hugozh.cn/shortcodes/figure/

relref 给的是根相对地址,因此即便用 Markdown 记法单独成行,也不会被 Markdown 渲染器自动包成链接(自动链接只认 http/https 开头的裸网址);ref 给的是完整网址,单独成行时会被自动包成链接。两个值分别贴进浏览器地址栏,打开的是同一页。

错误处理

默认情况下,Hugo 无法解析路径时会抛出错误并让构建失败。可以在项目配置中改为警告,并指定无法解析路径时返回的地址:

toml
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)。

别用:

  • 地址需要绝对形式(RSS、sitemap、站外分发)→ 用 ref;
  • Markdown 内容里的普通链接 → 优先用链接渲染钩子;
  • 链接站外地址 → relref 只管站内路径。

验证方法

  1. 在内容里写一次调用:

    content/example.mdmd
    参见 [另一篇文章]({{% relref "/posts/my-post" %}})。
  2. 构建并查看产物:

    bash
    hugo
  3. 打开 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/ 重新构建并检查部署目录

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