BundleType
返回给定页面的页面包类型;若该页面不是页面包,则返回空字符串。
这一页解决什么问题
Hugo 有三种「页面容器」:叶子包(目录里有 index.md)、分支包(目录里有 _index.md)和普通的 .md 文件。写通用模板(页头、SEO、资源处理)时经常要先知道当前页面属于哪一种,BundleType 就是这个问题的一句话答案:leaf、branch,或者空字符串(普通的独立页面)。
什么时候用,什么时候别用
该用:
- 模板需要区分「包」与「普通页面」:例如只有叶子包才把同目录的图片当作
.Resources; - 列表里想对包类页面用不同的摘要或图标。
别用:
- 只想判断「是不是普通内容页」→ 用
IsPage; - 想判断「是不是分支(section / 首页 / 分类法页)」→ 用
IsBranch(0.163.0 起,它取代了已弃用的IsNode); - 想拿到包内资源列表 →
BundleType只回答类型,取资源用.Resources。
用法
页面包(page bundle)是把内容与关联资源封装在一起的目录。页面包有两种类型:叶子包与分支包。详见说明。
Page 对象上的 BundleType 方法对分支包返回 branch,对叶子包返回 leaf,若该页面不是页面包则返回空字符串。
tree
content/
├── films/
│ ├── film-1/
│ │ ├── a.jpg
│ │ └── index.md <-- leaf bundle
│ ├── _index.md <-- branch bundle
│ ├── b.jpg
│ ├── film-2.md
│ └── film-3.md
└── _index.md <-- branch bundle在模板中取值:
go-html-template
{{ .BundleType }}完整示例:把三种容器各打印一次
最小站点结构:
tree
content/
├── docs/
│ ├── guide/
│ │ ├── _index.md <-- 分支包
│ │ ├── alpha.md <-- 普通页面
│ │ └── bundle/
│ │ ├── index.md <-- 叶子包
│ │ └── data.json <-- 叶子包的资源
│ └── _index.md
└── _index.md用同一个 layouts/_default/single.html 渲染所有普通页面:
layouts/_default/single.htmlgo-html-template
<p>{{ .Title }} → {{ with .BundleType }}{{ . }}{{ else }}(不是页面包){{ end }}</p>hugo --source <站点目录> --ignoreCache 构建后:
html
<p>Alpha → (不是页面包)</p>
<p>叶子包 → leaf</p>_index.md 渲染出的分支包页面,{{ .BundleType }} 得到:
html
branch你应当看到什么:普通 .md 页面返回的是空字符串(最容易误判的一种),必须用 with 或 eq 兜底;只有真正的包才有值。首页(content/_index.md)与各层 section 页同样返回 branch。同一次构建中 IsPage、IsBranch 的取值与之一致。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,Windows;内容结构见上。
| 页面 | 结果 | 是否报错 |
|---|---|---|
叶子包 bundle/index.md |
leaf |
否 |
分支包 _index.md(section 页、首页) |
branch |
否 |
普通页面 alpha.md |
空字符串(with 判为假) |
否 |
分类法页 /tags/、术语页 /tags/hugo/ |
branch(同一次构建中 IsBranch 为 true) |
否 |
| 返回类型 | string |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | 普通页面被当成包处理,或包被漏掉 | 普通页面返回空字符串,不是 nil 也不是 page |
先 with .BundleType,或显式判断 eq .BundleType "" |
| 没报错但结果不对 | 以为 .md 文件放进子目录就成了叶子包 |
叶子包要求文件名是 index.md(或 index.<语言>.md) |
把 alpha.md 改成 alpha/index.md |
| 没报错但结果不对 | 叶子包里 range .Resources 为空 |
资源必须与 index.md 放在同一目录 |
把资源文件移进包目录 |
更多排查入口见故障排查。