urls.Anchorize
返回给定字符串,并把它清理为可用于 HTML id 属性的形式。
这一页解决什么问题
写目录、脚注或「跳到某节」的链接时,需要一个能安全放进 HTML id 属性的值:不能有空格、<、& 这些字符。urls.Anchorize 把标题文本清理成这样的锚点字符串——Hugo 生成标题 id 时用的也是同一套规则(受 autoIDType 配置影响)。
什么时候用,什么时候别用
该用:
- 手工构造指向页内锚点的
href="#..."; - 想复现 Hugo 为标题生成的
id,用于自定义目录模板。
别用:
- 想清理成 URL 片段(要百分号编码)→ 用
urls.URLize:实测"Hugö"经anchorize得hugö,经urlize得hug%C3%B6; - 想给整个地址做转义 → 用
urls.PathEscape; - 页面标题本来就会自动生成
id,只是要做目录 → 用.TableOfContents,不必自己拼。
用法
- 用
anchorize函数生成 HTMLid属性的值 - 用
urlize函数把字符串清理为可用于 URL 的形式
例如:
go-html-template
{{ $s := "A B C" }}
{{ $s | anchorize }} → a-b-c
{{ $s | urlize }} → a-b-c
{{ $s := "a b c" }}
{{ $s | anchorize }} → a-b---c
{{ $s | urlize }} → a-b-c
{{ $s := "< a, b, & c >" }}
{{ $s | anchorize }} → -a-b--c-
{{ $s | urlize }} → a-b-c
{{ $s := "main.go" }}
{{ $s | anchorize }} → maingo
{{ $s | urlize }} → main.go
{{ $s := "Hugö" }}
{{ $s | anchorize }} → hugö
{{ $s | urlize }} → hug%C3%B6urls.Anchorize 函数会按项目配置中的 autoIDType 设置清理结果字符串。
完整示例(实测)
layouts/_partials/toc-link.htmlgo-html-template
[{{ anchorize "A B C" }}]|[{{ anchorize "a b c" }}]|[{{ anchorize "main.go" }}]Hugo 0.167.0 实测输出:
[a-b-c]|[a-b---c]|[maingo]你应当看到什么:空格变成短横,但连续的空格不会被合并(a b c 得 a-b---c 而不是 a-b-c);main.go 里的点被直接删掉,得到 maingo——这正是它与 urls.URLize 的关键差异。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,单语言站点(locale = 'zh-CN'),Windows,未修改 markup.goldmark.parser.autoIDType(上游默认 github)。
| 输入 | 结果 | 是否报错 |
|---|---|---|
"A B C" |
a-b-c |
否 |
"a b c" |
a-b---c(连续空格逐个变短横,不合并) |
否 |
"< a, b, & c >" |
-a-b--c-(标点变成短横,首尾也留下短横) |
否 |
"main.go" |
maingo(点被删除) |
否 |
"Hugö" |
hugö(非 ASCII 字母保留且转小写) |
否 |
| 返回类型 | string |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | 锚点链接点了没反应 | 生成的 id 与实际标题的 id 不一致(autoIDType 配置或标题文本对不上) |
直接检查渲染后的 id,不要凭猜测拼;或改用 .TableOfContents |
| 没报错但结果不对 | URL 里出现 hugö 导致 404 |
anchorize 只适合 id,不产生百分号编码 |
生成 URL 片段用 urls.URLize |
| 没报错但结果不对 | 目录里的锚点与标题不一致 | 标题里含连续空格或标点时的处理规则与直觉不同 | 用本页实测表对照,或让 Hugo 自己生成目录/锚点 |
更多排查入口见故障排查。