RelPermalink
返回当前输出格式所生成页面的相对永久链接。
这一页解决什么问题
RelPermalink 返回「当前输出格式生成的那份文件」的根相对地址:以 / 开头,不带协议与域名,但带站点子路径。它适合放进同站的 <a href>、<link href>、<img src>——换域名、换预览端口都不影响。
它与 Permalink 的唯一差别就是「带不带域名」:实测首页 rss 格式在 baseURL = "https://example.org/" 下是 /index.xml,在 https://example.org/docs/ 下是 /docs/index.xml。
什么时候用,什么时候别用
该用:
- 同站链接:
<a href>、<link rel="stylesheet" href>、<img src>、<link rel="alternate" href>; - 需要地址随
baseURL的子路径自动调整,而不希望把域名写进产物。
别用:
- 需要绝对地址的场合:RSS/Atom 自动发现、Open Graph、结构化数据、邮件模板 → 用
Permalink; - 只想知道格式名或后缀 → 用
Name、MediaType; - 想拿页面本身(而不是某个输出格式)的相对地址 → 用页面上的
RelPermalink方法。
基本用法
要使用该方法,你必须先通过 Get 或 Canonical 方法,从页面的 OutputFormats 集合中选出特定的 output format(输出格式)。
go-html-template
{{ with .Site.Home.OutputFormats.Get "rss" }}
{{ .RelPermalink }} → /index.xml
{{ end }}完整示例:给页面加上 RSS 链接
layouts/_partials/head.htmlgo-html-template
{{ with site.Home.OutputFormats.Get "rss" }}
<link rel="alternate" type="application/rss+xml" href="{{ .RelPermalink }}">
{{ end }}baseURL = "https://example.org/" 时,Hugo 渲染为:
html
<link rel="alternate" type="application/rss+xml" href="/index.xml">把 baseURL 换成 https://example.org/docs/ 后,实测渲染为:
html
<link rel="alternate" type="application/rss+xml" href="/docs/index.xml">你应当看到什么:地址以 / 开头,没有域名;子路径部署时 /docs/ 前缀自动出现——这正是它与 Permalink 的差别。若同时在页面上输出两种格式的列表,实测 html 得到 /docs/、rss 得到 /docs/index.xml。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,单语言站点,Windows。
| 情况 | 结果 | 是否报错 |
|---|---|---|
首页 html 输出格式 |
/(子路径部署时 /docs/) |
否 |
首页 rss 输出格式 |
/index.xml(子路径部署时 /docs/index.xml) |
否 |
自定义 baseName = 'search' 的 application/json 输出格式 |
/docs/search.json |
否 |
输出格式没有配置 mediaType |
/bare——没有后缀 |
否 |
Get 取不到(名字没启用) |
空串(with 判为假);不判断直接拼进属性会得到 href="" |
否 |
| 返回类型 | string,永远不会是 nil |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | RSS 阅读器抓不到 feed | 写进了相对地址,消费方要求绝对地址 | 改用 Permalink |
| 没报错但结果不对 | 站点部署到子路径后链接 404 | baseURL 没写子路径,或漏了结尾斜杠 |
让 baseURL 与部署位置一致,必要时用 --baseURL 覆盖 |
| 没报错但结果不对 | 产物里出现 href="" |
Get 取不到时给空值,不报错 |
用 with 包住整段 |
| 报错看不懂 | 页面里原样出现 {{ .RelPermalink }} 字样 |
把模板代码写进了内容 Markdown:内容文件不是模板 | 在模板里生成地址,或改用短代码 |
更多排查入口见故障排查。