短代码

ref

用 ref 短代码插入指向指定页面的永久链接:路径解析规则、必须用 Markdown 记法的原因、参数表与报错处理。

难度
入门
预计用时
10 分钟

开始之前,你需要

  • 站点能构建成功(hugo --renderToMemory 退出码为 0),站内有至少两个页面可以互链。
  • 读过短代码里「两种记法」一节,知道 Markdown 记法与标准记法的区别。

读完之后你能

  • 写出指向站内页面的 ref 调用,并说清它输出的是绝对地址还是相对地址;
  • 判断什么时候必须用 Markdown 记法调用(放进 Markdown 链接里时),并知道用错会出什么现象;
  • 配置 refLinksErrorLevel / refLinksNotFoundURL,让找不到页面时的行为符合你的发布流程。

接着读:relref · 链接

这一页解决什么问题

正文里要链接到另一篇内容,直接写 /posts/my-post/ 行不行?在这个站点里行得通,但一旦改了 URL 结构、换了 baseURL、或者做多语言,这个写死的地址就静默失效了——Markdown 不会告诉你链接坏了。

ref 短代码把「路径」交给 Hugo 去查:你写内容文件在站内的逻辑路径,Hugo 在构建时把它解析成包含站点地址的永久链接(permanent link)。地址写错时 Hugo 会报错(可配置成警告),而不是安静地生成一个死链。

要的是「不含域名、便于迁移的相对地址」时,用 relref,两者参数与解析规则完全相同。

用法

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

参数

path
(string)目标页面的路径。不以斜杠(/)开头的路径先相对当前页面解析,再相对站点其余部分解析。也可以直接写带扩展名的文件名,例如 book-1.md(实测可用)。
lang
(string)目标页面的语言。默认为当前语言。可选。
outputFormat
(string)目标页面的输出格式。默认为当前输出格式。可选。

示例

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

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

md
[Link A]({{% ref "/books/book-1" %}})

[Link B]({{% ref path="/books/book-1" %}})

[Link C]({{% ref path="/books/book-1" lang="de" %}})

[Link D]({{% ref path="/books/book-1" lang="de" outputFormat="json" %}})

渲染结果:

html
<a href="https://example.org/en/books/book-1/">Link A</a>

<a href="https://example.org/en/books/book-1/">Link B</a>

<a href="https://example.org/de/books/book-1/">Link C</a>

<a href="https://example.org/de/books/book-1/index.json">Link D</a>

为什么必须用 Markdown 记法

上面那条 [Markdown 写法][] 的提醒不是格式洁癖,而是能不能解析出链接的硬条件:ref 的输出要落在 Markdown 链接的目标地址位置上,而目标地址是 Markdown 渲染器负责解析的,所以短代码必须在 Markdown 渲染之前就把地址填进去。

实测(Hugo 0.167,单语言站点) 在同一段内容里对比几种写法,结果如下:

对照阅读请注意测量条件不同:上面「渲染结果」取自上游的多语言示例站点,地址带默认语言前缀 /en/;下表实测跑在单语言站点上,因此没有语言前缀。两者验证的都是「这种写法能否解析出链接」,与地址前缀无关。

写法 渲染结果
[Link A]({{% ref "/books/book-1" %}}) <a href="https://example.org/books/book-1/">Link A</a>(正常)
[Link B]({{< ref "/books/book-1" >}}) <a href="https://example.org/books/book-1/">Link B</a>(本站实测同样正常,见下方更正)
[Link D]({{% relref "/books/book-1" %}}) <a href="/books/book-1/">Link D</a>(正常,相对地址)
  • 用 Markdown 记法(A、D)→ 链接正常;
  • 用标准记法(B)→ 上游文档说 href 会被解析成空值;这一点本站复现不出来,见下方更正;
  • 短代码单独成行时(不在链接里),两种记法都能用。但结果略有差别:Markdown 记法的输出会被 Markdown 渲染器当成裸网址,自动包成链接;标准记法输出的是纯文本。

本站实际渲染效果

下面三处都是本站页面里的真实调用,构建时展开:

ref 的典型用途:给 HTML 链接填地址

看看 figure 那一页——地址由 ref 短代码生成,带完整域名。

填进 Markdown 链接时两种记法都能用(本站这一页两种都写了,你可以把鼠标悬停在链接上看地址):

单独成行时才看得出记法的差别——下面两处调用写法不同,请对照它们能不能点:

Markdown 记法(输出被 Markdown 渲染器自动包成链接):

https://hugozh.cn/shortcodes/figure/

标准记法(输出是纯文本,不可点):

https://hugozh.cn/shortcodes/figure/

错误处理

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

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

两个配置项的行为要分清:

配置 默认值 作用
refLinksErrorLevel ERROR 找不到目标页面时的日志级别;ERROR 会让构建失败,改成 warning 则只打印警告
refLinksNotFoundURL 未设置 解析失败时用来替换的地址

实测(Hugo 0.167,refLinksErrorLevel = 'warning' 且设置了 refLinksNotFoundURL):

情况 构建输出 页面上的地址
路径不存在(/books/nope) WARN [en] REF_NOT_FOUND: Ref "/books/nope": "…/content/_index.en.md:26:1": page not found 替换成 refLinksNotFoundURL 的值
outputFormat 在当前语言下不存在(如只要 HTML 输出却写 outputFormat="json") WARN [de] REF_NOT_FOUND: Ref "/books/book-1" from page "/": output format "json" 同样替换成 refLinksNotFoundURL 的值

两个警告都带 文件:行:列,可以直接定位到出问题的调用。

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

该用:

  • 正文里做站内互链,又想避免写死地址;
  • 链接目标需要跨语言(lang)或指向非 HTML 输出格式(outputFormat);
  • 用 refLinksErrorLevel = 'ERROR'(默认)当作「链接检查器」,让坏路径在构建时失败。

别用:

  • Markdown 内容里的普通链接 → 优先用链接渲染钩子:它同样解析 Markdown 目标地址,而且不需要在链接里嵌短代码(本页开头的提示正是这个意思);
  • 链接到站外地址 → 直接写 Markdown 链接,ref 只管站内路径;
  • 想要的是不含域名的地址 → 用 relref;
  • 目标页面当前构建中不存在(草稿、未来日期、被 build.render 关掉)→ ref 会解析失败,先确认那页真的会被渲染。

验证方法

  1. 在内容里写一次调用,把它放进 Markdown 链接:

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

    bash
    hugo
  3. 打开 public/example/index.html,搜索 my-post。

你应当看到什么:<a href="https://你的域名/posts/my-post/">另一篇文章</a>——地址里带域名(这是 ref 与 relref 的唯一区别)。

  • 如果 href 是空的 → 检查是不是用了标准记法,或页面路径写错了;
  • 如果构建直接失败并提示 REF_NOT_FOUND → 说明这个路径确实不存在,按报错里的 文件:行:列 去改;
  • 如果产物里还有短代码定界符的字样 → 定界符被转义了,或这段内容没被渲染。

常见坑

类别 现象 真因 怎么修
没报错但结果不对 链接点不动,href="" 用标准记法调用,且短代码嵌在 Markdown 链接的目标地址里 改用 Markdown 记法(% 定界符)
没报错但结果不对 href 整段不见了 同上,或目标页面不会被渲染(草稿、未来日期、被 build.render 关掉) 确认该页确实会被构建出来
报错看不懂 REF_NOT_FOUND 路径在站点里不存在;路径是相对当前页面解析的,可能基准不对 用根相对路径(以 / 开头)最稳妥;多语言站点确认 lang
报错看不懂 警告里出现你没想到的语言(如 [de]) lang 指向的语言没有该页面或其输出格式 确认目标语言里确实有这一页
报错看不懂 构建成功,但线上链接 404 改了 URL 结构却没重新构建,或部署了旧的 public/ 重新构建并检查部署目录

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