Hugo Site.RegularPages 方法完全指南：遍历站点全部普通页面与默认排序规则

开发工具前端CLI【免费下载链接】hugoThe world’s fastest framework for building websites.项目地址https://gitcode.com/gh_mirrors/hu/hugo点击查看免费下载Site.RegularPages是 Hugo 站点对象上用于获取当前语言下全部[普通页面]regular pages集合的方法返回类型为page.Pages。本文以 RegularPages 方法文档 为主体结合仓库源码site.go、hugo_sites.go与测试用例系统讲解其语义、模板用法、默认排序规则、排序方法链以及与Site.Pages、Page.RegularPages的差异帮助你在首页、列表页等模板中准确、高效地遍历全部正文页面。方法签名与返回值依据 RegularPages.md 的 front matter该方法的元数据为方法名RegularPages所属对象Site即模板中的.Site返回类型page.PagesHugo 的页面集合类型调用形式SITE.RegularPages在模板中的调用形式为{{ .Site.RegularPages }}。该方法在Site对象上的实现位于 hugolib/site.go// RegularPages returns all the regular pages. // This is for the current language only. func (s *Site) RegularPages() page.Pages { s.CheckReady() return s.pageMap.getPagesInSection( pageMapQueryPagesInSection{ Path: , KeyPart: global, Include: pagePredicates.ShouldListGlobal.And(pagePredicates.KindPage).BoolFunc(), Recursive: true, }, ) }从源码可以确认三个关键语义仅返回当前语言源码注释明确This is for the current language only返回的是当前语言站点的普通页面不会跨语言混合。递归收集查询参数Recursive: true表示从站点根Path: 向下递归收集所有普通页面而不是只取某一层。过滤条件Include中KindPage谓词限定只包含 kind 为page的页面排除了首页home、section、taxonomy、term 等其他页面种类这正是“普通页面”的定义所在。若需要在多语言站点中聚合所有语言的普通页面可使用AllRegularPages()site.go它内部调用HugoSites.RegularPages()hugo_sites.go将所有Site的结果合并后统一按默认顺序排序并通过cachePages缓存。什么是普通页面regular page在 Hugo 中页面page分为多种页面种类kinds首页home、分节页section、分类页taxonomy、术语页term和普通页面page。普通页面即那些由具体内容文件如contact.md、posts/hello.md渲染生成的正文页面它们不包含_index.md分支页面所代表的列表性质。Site.RegularPages与Site.Pages的核心区别在于参见 Pages.md方法返回内容适用场景Site.Pages当前语言下所有页面种类包括首页、section、taxonomy、term 和普通页面一般建议优先使用RegularPagesSite.RegularPages当前语言下全部普通页面列表页、RSS、站点地图等绝大多数正文遍历场景Site.Pages的实现同样位于 hugolib/site.go其Include使用ShouldListGlobal而未限定KindPage因此会包含所有页面种类。官方文档在 Pages.md 中明确建议“在大多数情况下你应该使用RegularPages方法替代”——这正体现了RegularPages作为最常用遍历入口的地位。模板中的基本用法Site.RegularPages返回一个page.Pages集合天然支持 Go 模板的range遍历。文档 RegularPages.md 给出的最基础用法{{ range .Site.RegularPages }} h2a href{{ .RelPermalink }}{{ .LinkTitle }}/a/h2 {{ end }}在 range 循环体内上下文切换到每一个普通页面对象因此可以访问页面的属性与方法{{ .RelPermalink }}输出页面相对永久链接{{ .LinkTitle }}输出链接标题默认取页面标题可配置。这是构建首页文章列表、博客归档页最常用的模式。结合Page.RegularPagespage/RegularPages.md可进一步理解当用于home、section、taxonomy、term这四类页面种类时Page.RegularPages返回的是当前节section内的普通页面而当用于Site对象时返回的是全站递归的所有普通页面——二者的区别正是Recursive: true与节内查询的差别。默认排序规则default sort order文档说明Site.RegularPages返回的集合遵循 Hugo 的 [default sort order]默认排序。该排序在Site.RegularPages查询返回后由 content_map_page.go 等处的page.SortByDefault应用其实现位于 resources/page/pages_sort.go// SortByDefault sorts pages by the default sort. func SortByDefault(pages Pages) { pageBy(DefaultPageSort).Sort(pages) }默认排序的优先级DefaultPageSort定义于pages_sort.go顶部依次为Weight权重front matter 中设置的weight值越小越靠前常用于手动固定顺序Date日期页面date较早的日期排在前面LinkTitle链接标题linkTitle缺省时回退到titlePath路径按内容文件路径排序作为最终稳定排序依据。例如在 hugo_smoke_test.go 中测试通过b.H.Sites[0].RegularPages()断言了多语言站点的普通页面数量161 与 158 个而 site_test.go 则验证了排序后首个页面标题为doc1这些测试都依赖默认排序的稳定性。使用排序方法改变顺序默认顺序不满足需求时可以对返回的page.Pages集合直接调用排序方法。文档 RegularPages.md 给出了按标题排序的示例{{ range .Site.RegularPages.ByTitle }} h2a href{{ .RelPermalink }}{{ .Title }}/a/h2 {{ end }}page.Pages提供了一整套排序方法详见 methods/pages/ 相关文档与 pages_sort.go常用包括排序方法排序依据源码位置ByTitle按标题排序pages_sort.goByLinkTitle按链接标题排序pages_sort.goByDate按日期排序pages_sort.goByPublishDate按发布日期排序pages_sort.goByWeight按权重排序pages_sort.goByExpiryDate、ByLastmod、ByLength、ByParam等按相应属性排序同文件后续定义值得注意的是排序方法的实现大多通过spc.get缓存如ByTitle的pageSort.ByTitle键同一接收者上重复调用会返回缓存结果且设计上可安全并行执行注释明确This may safely be executed in parallel。因此即使在同一模板中多次调用排序方法性能开销也很小。与其他方法的对比与最佳实践Site.RegularPages与Site.Pages如前所述Site.Pages返回全部页面种类包括首页、section、taxonomy、term 与普通页面。若在其上遍历渲染文章列表会把列表页本身也渲染成条目通常不符合预期。因此官方文档建议“在大多数情况下使用RegularPages”。Site.RegularPages与Page.RegularPagesSite.RegularPages递归返回全站所有语言当前语言的普通页面Page.RegularPages用于 home/section/taxonomy/term 页面返回当前节内的普通页面不递归到子节除非子目录没有_index.md而归属当前节。参考 page/RegularPages.md 的内容结构示例当lessons节下存在lesson-1/、lesson-2/等子目录时渲染lessons节页面时.RegularPages只返回grading-policy.md与lesson-plan.md而渲染lesson-2时由于resources/目录没有_index.md不是独立节其下的task-list.md、worksheet.md也属于lesson-2节会被一并返回。该文档还特别提示“当用于Site对象时RegularPages方法会递归返回站内所有普通页面”。RegularPagesRecursive若在节section页面上需要递归获取该节下所有子节的普通页面可参考Page.RegularPagesRecursivehugolib/page.go它对section与home种类使用Recursive: true递归查询对其他种类回退到RegularPages。实际应用场景首页文章列表最常用ul {{ range .Site.RegularPages }} lia href{{ .RelPermalink }}{{ .LinkTitle }}/a/li {{ end }} /ul按日期倒序的博客归档{{ range .Site.RegularPages.ByDate.Reverse }} h3a href{{ .RelPermalink }}{{ .Title }}/a/h3 p{{ .Date.Format 2006-01-02 }}/p {{ end }}Reverse是page.Pages提供的反转方法将默认升序改为降序。结合分页在列表模板中常与 pagination 结合{{ $paginator : .Paginate .Site.RegularPages }}随后range $paginator.Pages渲染分页后的页面集合。小结Site.RegularPages返回当前语言下全部普通页面递归收集、默认排序返回类型page.Pages模板中通过{{ range .Site.RegularPages }}遍历循环体内可访问各页面属性默认排序依次为 Weight → Date → LinkTitle → Path可用ByTitle、ByDate等排序方法改变顺序与Site.Pages、Page.RegularPages、AllRegularPages的区别要点已在上文表格中归纳。掌握Site.RegularPages是编写 Hugo 列表类模板的基础几乎所有需要“全站正文页面”的场景都能由此入口高效完成。赞分享开发工具前端CLI【免费下载链接】hugoThe world’s fastest framework for building websites.项目地址https://gitcode.com/gh_mirrors/hu/hugo点击查看免费下载相关推荐Hugo 页面集合排序方法 ByDate 完全指南按日期升序排序与 Reverse 降序实战Hugo 页面集合排序方法 ByDate 完全指南按日期升序排序与 Reverse 降序实战 ByDate 是 Hugo 模板系统中 Pages 集合类型的一开发工具前端CLIHugo 页面集合按内容长度排序PAGES.ByLength 方法完全指南Hugo 页面集合按内容长度排序PAGES.ByLength 方法完全指南 Pages.ByLength 是 Hugo 模板中用于将页面集合 page.Pa开发工具前端CLIHugo Page.RegularPages 方法完全指南section 内常规页面集合的获取、排序与底层实现Hugo Page.RegularPages 方法完全指南section 内常规页面集合的获取、排序与底层实现 导读 在 Hugo 模板开发中 Page.R开发工具前端CLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考