Page

Sections

返回 section 页面集合,给定页面的每一个直属子 section 对应一个页面。

签名
PAGE.Sections
返回类型
page.Pages

这一页解决什么问题

要在首页或栏目页里列出「子栏目」,.Sections 是最直接的方法:它只返回直属子 section 的 section 页,不掺常规页面。做「栏目导航」「文档站左侧的章节列表」时用它;如果写成 .Pages,还得自己把常规页面过滤掉。

它和 .Pages、.RegularPages 的分工:

方法 返回
.Sections 只有直属子 section 页
.Pages 当前层常规页面 + 直属子 section 页
.RegularPages 只有当前层常规页面

什么时候用,什么时候别用

该用:

  • 首页/栏目页的「栏目列表」「章节导航」;
  • 只想遍历子 section(要它们的 Title、RelPermalink、.Pages)。

别用:

  • 要连常规页面一起列 → 用 .Pages;
  • 要所有后代 section、更深层也算 → 没有现成方法,需自己递归 .Sections;
  • 在常规内容页上调用 → 实测返回空集合(只服务 home、section、taxonomy)。

在已知的 section 页上,len(.Pages) == len(.RegularPages) + len(.Sections)(实测 /docs/:2 = 1 + 1)——但 taxonomy 页是例外:它的 .Pages 是术语页,.RegularPages 与 .Sections 都是空(实测 /tags/ 为 2 = 0 + 0),所以不要把这个等式当成通用规律。

用法

Page 对象上的 Sections 方法可用于这些页面类型:home、section 和 taxonomy。这些页面类型的模板会在上下文中接收一个页面集合,并按默认排序顺序排列。

内容结构如下:

tree
content/
├── auctions/
│   ├── 2023-11/
│   │   ├── _index.md     <-- front matter: weight = 202311
│   │   ├── auction-1.md
│   │   └── auction-2.md
│   ├── 2023-12/
│   │   ├── _index.md     <-- front matter: weight = 202312
│   │   ├── auction-3.md
│   │   └── auction-4.md
│   ├── _index.md         <-- front matter: weight = 30
│   ├── bidding.md
│   └── payment.md
├── books/
│   ├── _index.md         <-- front matter: weight = 20
│   ├── book-1.md
│   └── book-2.md
├── films/
│   ├── _index.md         <-- front matter: weight = 10
│   ├── film-1.md
│   └── film-2.md
└── _index.md

模板如下:

go-html-template
{{ range .Sections.ByWeight }}
  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}

在首页上,Hugo 渲染出:

html
<h2><a href="/films/">Films</a></h2>
<h2><a href="/books/">Books</a></h2>
<h2><a href="/auctions/">Auctions</a></h2>

在 auctions 页面上,Hugo 渲染出:

html
<h2><a href="/auctions/2023-11/">Auctions in November 2023</a></h2>
<h2><a href="/auctions/2023-12/">Auctions in December 2023</a></h2>

完整示例:首页栏目导航

测试站结构:顶层有 /posts/(无子 section)与 /docs/(含子 section /docs/guide/)。

首页模板:

layouts/index.htmlgo-html-template
<nav>
  {{ range .Sections.ByWeight }}
    <a href="{{ .RelPermalink }}">{{ .Title }}</a>
  {{ end }}
</nav>

实测(Hugo 0.167.0)渲染首页:

html
<nav>
  <a href="/posts/">文章</a>
  <a href="/docs/">文档</a>
</nav>

如果在循环里写 {{ len .RegularPages }},注意 点号已经变成子 section,取到的是该子 section 自己的常规页面数——实测首页上依次得到 /posts = 10、/docs = 1(/docs 的直接常规页面只有 ref.md 一个,guide/ 的子页面不算)。

其他页面实测:

渲染的页面 range .Sections 得到
/(首页) /posts、/docs
/docs/ /docs/guide
/posts/(无子 section) 空
/docs/guide/(无子 section) 空
/tags/(taxonomy) 空

你应当看到什么:/docs/ 的 .Sections 只有 /docs/guide(不含常规页面 /docs/ref),而它的 .RegularPages 只有 /docs/ref。range 里点号是子 section 页,所以 .Title、.RelPermalink、.RegularPages 全都属于那个子 section。

返回值边界(实测)

情况 结果 是否报错
首页 所有顶层 section 页(实测 2 条) 否
有子 section 的 section 直属子 section 页(实测 /docs/ → 1 条) 否
无子 section 的 section 空集合(len 为 0,if 为假) 否
taxonomy 页 实测空集合 否
常规内容页 空集合 否
更深层的子 section 不递归:只返回直属一层 否
返回类型 page.Pages(可 .ByWeight、.ByTitle) 否

更多排查入口见故障排查。