Rel
返回给定输出格式的 rel 值,可以是默认值,也可以是项目配置中定义的值。
这一页解决什么问题
Rel 返回写进 <link rel="…"> 里的那个值。它由两处决定:
- 默认:规范输出格式(canonical,通常是
html)得到canonical,其余可替换输出格式得到alternate; - 项目配置:给该输出格式写了
rel就以配置为准(实测写成rel = 'search'后.Rel返回search)。
模板里不要把 "alternate" 硬编码——主题一旦被别的站点复用,或者用户改了配置,硬编码的值就和实际不符了。
什么时候用,什么时候别用
该用:
- 生成
<link rel="{{ .Rel }}" type="…" href="…">:让规范格式与备用格式各自得到正确的值; - 需要区分「这一份是不是规范输出格式」:规范的那份实测
.Rel为canonical。
别用:
- 需要地址 → 用
Permalink或RelPermalink; - 需要
type属性 → 用MediaType.Type; - 想让某份输出不出现在
rel="alternate"列表里 → 那是输出格式的notAlternative配置项,不是Rel。实测把notAlternative = true的自定义格式取出来,.Rel仍然是alternate。
基本用法
要使用该方法,你必须先通过 Get 或 Canonical 方法,从页面的 OutputFormats 集合中选出特定的 output format(输出格式)。
go-html-template
{{ with .Site.Home.OutputFormats.Get "rss" }}
{{ .Rel }} → alternate
{{ end }}完整示例:同时输出备用 feed 与规范地址
layouts/_partials/head.htmlgo-html-template
{{ with site.Home.OutputFormats.Get "rss" }}
<link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .RelPermalink }}">
{{ end }}
{{ with site.Home.OutputFormats.Canonical }}
<link rel="{{ .Rel }}" href="{{ .Permalink }}">
{{ end }}测量条件:Hugo 0.167.0 extended,单语言最小站点,baseURL = "https://example.org/",首页输出格式为默认的 html 与 rss。Hugo 渲染为:
html
<link rel="alternate" type="application/rss+xml" href="/index.xml">
<link rel="canonical" href="https://example.org/">你应当看到什么:rss 拿到了 alternate,规范输出格式(html)拿到了 canonical,地址一个用相对、一个用绝对。第一行的 + 是 html/template 对 + 做 HTML 转义的结果,浏览器解析属性值后仍是 application/rss+xml。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,单语言站点,Windows。
| 情况 | 结果 | 是否报错 |
|---|---|---|
首页 rss,配置里没写 rel |
alternate |
否 |
首页 Canonical(html) |
canonical |
否 |
自定义输出格式配置了 rel = 'search' |
search——配置优先于默认值 |
否 |
自定义输出格式配置了 notAlternative = true |
仍是 alternate——该配置不影响 .Rel |
否 |
Get 取不到(该格式没启用) |
空串(with 判为假);不判断直接用会得到 rel="" |
否 |
| 返回类型 | string,永远不会是 nil |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | 自定义输出格式在 <link> 里被标成 alternate,不符合预期 |
rel 默认就是 alternate,notAlternative 只管「要不要列进备用格式」 |
给该输出格式显式配置 rel |
| 没报错但结果不对 | 两个 <link> 都拿到 canonical,或都拿到 alternate |
分别用了 .OutputFormats.Canonical 与 Get,取到的不是同一个对象 |
想标备用格式就用 Get,想标规范格式才用 Canonical |
| 没报错但结果不对 | 产物里出现 rel="" |
Get 取不到时不报错,给的是空值 |
用 with 包住整段 |
| 报错看不懂 | 提示找不到 Rel 字段 |
对页面(而不是 OutputFormat 对象)取了 .Rel |
先用 Get/Canonical 取出对象再取 .Rel |
更多排查入口见故障排查。