urls.URLize
返回给定字符串,并把它清理为可用于 URL 的形式。
这一页解决什么问题
把一个人类可读的字符串变成 URL 里能用的片段:术语名 "Victor Hugo" 对应术语页地址里的 victor-hugo。Hugo 生成术语页、页面文件名对应的 slug 时用的就是这套转换,所以想手工拼出与 Hugo 产物一致的地址时,必须用 urls.URLize。
什么时候用,什么时候别用
该用:
- 按术语名查
.Site.Taxonomies(见下文上游示例); - 需要与 Hugo 自动生成的路径保持一致的场景。
别用:
- 想要 HTML
id(锚点)→ 用urls.Anchorize:实测"main.go"经urlize得main.go(保留点),经anchorize得maingo(删掉点); - 想把含空格/中文的字符串作为路径片段做百分号编码 → 用
urls.PathEscape; - 想拼完整地址 → 用
urls.JoinPath、urls.AbsURL、urls.RelURL。
用法
- 用
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%B6用 urlize 函数可以创建指向术语页面(term page)的链接。
假设项目配置如下:
toml
[taxonomies]
author = 'authors'前置元数据如下:
toml
title = 'Les Misérables'
authors = ['Victor Hugo']发布后的站点将具有这样的结构:
tree
public/
├── authors/
│ ├── victor-hugo/
│ │ └── index.html
│ └── index.html
├── books/
│ ├── les-miserables/
│ │ └── index.html
│ └── index.html
└── index.html要创建指向术语页面的链接:
go-html-template
{{ $taxonomy := "authors" }}
{{ $term := "Victor Hugo" }}
{{ with index .Site.Taxonomies $taxonomy (urlize $term) }}
<a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a>
{{ end }}要生成与某个内容页面关联的术语页面列表,请在 Page 对象上使用 GetTerms 方法。
完整示例(实测)
layouts/_partials/term-link.htmlgo-html-template
[{{ urlize "A B C" }}]|[{{ urlize "a b c" }}]|[{{ urlize "Hugö" }}]Hugo 0.167.0 实测输出:
[a-b-c]|[a-b-c]|[hug%C3%B6]你应当看到什么:与 anchorize 的两处差异一眼可见——a b c 的连续空格被合并成一个短横(a-b-c),非 ASCII 字符 ö 被百分号编码成 %C3%B6(hug%C3%B6),而 anchorize 会原样保留 hugö。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,单语言站点(locale = 'zh-CN'),Windows。
| 输入 | 结果 | 是否报错 |
|---|---|---|
"A B C" |
a-b-c |
否 |
"a b c" |
a-b-c(连续空格合并) |
否 |
"< a, b, & c >" |
a-b-c(标点被丢弃,不在首尾留短横) |
否 |
"main.go" |
main.go(点保留) |
否 |
"Hugö" |
hug%C3%B6(非 ASCII 百分号编码) |
否 |
| 返回类型 | string |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | 术语链接 404 | 手工把术语名转成了 victor hugo、Victor-Hugo 之类,与 Hugo 生成的不一致 |
一律用 urlize 转换后再查 Taxonomies(上游示例即如此) |
| 没报错但结果不对 | 锚点里出现 %C3%B6 |
用 urlize 生成了 id |
生成 id 用 urls.Anchorize |
| 没报错但结果不对 | 中文标题的 URL 与预期不同 | 中文会被转成百分号编码 | 以站点实际产物的目录名为准,必要时给页面显式设置 url |
更多排查入口见故障排查。