开发工具前端CLI【免费下载链接】hugoThe world’s fastest framework for building websites.项目地址https://gitcode.com/gh_mirrors/hu/hugo点击查看免费下载列表页list page是 Hugo 站点中负责聚合展示的一类页面它接收一个页面集合page collection作为模板上下文将同类型的页面统一渲染。本文基于 Hugo 官方术语表对列表页的定义结合本仓库源码与官方文档系统讲解列表页的判定标准、四类典型列表页、模板选择机制以及分页实战帮助你精准掌控_default/list.html的编写与扩展。什么是列表页Hugo 官方定义在 Hugo 官方术语表 中list-page词条给出如下定义见 list-page.mdA list page is anypage kindthat receives a pagecollectionincontext. This includes the home page,section pages,taxonomy pages, andterm pages.即列表页是任何在上下文context中接收到页面集合collection的页面种类page kind具体包括首页home page、栏目页section page、分类页taxonomy page和术语页term page四类。这个定义由三个基础术语支撑理解它们是掌握列表页的前提页面种类page kindHugo 对页面的分类取值仅有home、page、section、taxonomy、term五种见 page-kind.md。集合collection即数组array、切片slice或映射map这类可迭代的数据结构见 collection.md。上下文context在模板动作中用点号.表示指当前所处数据结构的位置。例如遍历一个页面集合时每次迭代的上下文就是该页面的数据结构每个模板接收的上下文取决于模板类型及其调用方式见 context.md。五种页面种类中谁是列表页Hugo 将页面划分为五种 kind其中只有page普通页面不是列表页页面种类kind是否列表页上下文内容home✅全站页面集合page❌单篇内容由_default/single.html渲染section✅当前栏目内的页面集合taxonomy✅某分类下的术语term集合term✅拥有某术语的页面集合官方模板文档对此有直接说明页面种类决定了它属于single page普通内容页HTML 输出查找_default/single.html还是list page栏目列表、首页、分类列表、分类术语HTML 输出查找_default/list.html参见 模板查找顺序文档。从源码结构也可以印证这一点在 resources/page/page.go 的ChildCareProvider接口中Pages()返回所有 kind 的页面列表RegularPages()只返回 kind 为page的普通页面而RegularPagesRecursive()返回当前栏目下所有层级的普通页面——这些方法正是列表页模板中获取页面集合的核心入口。四类列表页逐一拆解1. 首页home pagehome是站点的唯一入口页也是列表页中上下文最宽的一类它的页面集合覆盖整个站点的内容。首页模板的典型写法是遍历site.RegularPages或.Pages来输出全站文章列表常与分页配合使用详见下文。2. 栏目页section page栏目页是 kind 为section的页面通常列出当前栏目内的普通页面regular pages和/或其它栏目页见 section-page.md。关于栏目与列表页的关系栏目Sections文档 给出了关键对比目录名会成为 URL 路径段只有栏目含_index.md的目录才有列表页栏目具有逻辑上的祖先与后代关系非栏目目录则没有。文档中还特别强调products 栏目的列表页默认只包含product-1、product-2这类直接子项不包含更深层级的后代页面若希望列出栏目下所有层级的普通页面应在栏目模板中使用RegularPagesRecursive方法而非Pages——这正是 resources/page/page.go 中该方法的接口语义。3. 分类页taxonomy page分类页是 kind 为taxonomy的页面通常列出给定分类taxonomy内的术语terms见 taxonomy-page.md。以 分类Taxonomies文档 中的电影站为例其数据组织层级为Actor - Taxonomy分类 Bruce Willis - Term术语 The Sixth Sense - Value内容 Unbreakable - ValueHugo 会根据内容 front matter 中声明的分类字段自动为每个 Actor、Director、Studio 等生成分类页每个分类页再列出匹配的术语。4. 术语页term page术语页是 kind 为term的页面通常列出拥有某个给定术语的普通页面和栏目页见 term-page.md。沿用上面的例子/actors/bruce-willis/就是一个术语页它的页面集合包含所有在 front matter 中标注了actors: [Bruce Willis]的电影页面。列表页的模板选择查找顺序与命名约定列表页统一使用_default/list.html作为兜底模板但 Hugo 提供了按 kind、layout、输出格式、语言等维度逐级精确匹配的查找机制。以 HTML 输出为例四类列表页的常用模板命名如下列表页类型推荐模板路径全站通用layouts/_default/list.html首页专用layouts/index.html栏目页layouts/_default/section.html或layouts/section/list.html分类页layouts/_default/taxonomy.html术语页layouts/_default/term.html模板查找的完整优先级规则按具体程度从高到低考虑 kind、layout、输出格式、语言、type、section 等参数详见 模板查找顺序文档。其中 kind 是最重要的维度之一Hugo 据此判断是渲染单页还是列表页并决定回退到single.html还是list.html。一个最小可用的列表页模板示例layouts/_default/list.html{{ define main }} h1{{ .Title }}/h1 ul {{ range .Pages }} lia href{{ .RelPermalink }}{{ .LinkTitle }}/a/li {{ end }} /ul {{ end }}其中.Pages即为该列表页上下文中的页面集合若只想列出普通页面可改用.RegularPages若当前是栏目页且需要包含所有后代层级则使用.RegularPagesRecursive。列表页分页Paginate 与 Paginator当列表页承载的页面集合较大时分页Pagination文档 明确指出应优先为home、section、taxonomy、term这四类列表页开启分页以提升可读性与加载性能。分页相关术语paginate动词将列表页拆分为两个或更多子集见 paginate.mdpagination名词对列表页执行分页的过程见 pagination.mdpager分页过程中创建的对象包含列表页的一个子集及指向其它 pager 的导航链接见 pager.md。两种分页方法在列表页模板中可对Page对象调用以下任一方法Paginate更灵活可对任意页面集合分页支持先过滤、排序、分组并可覆盖项目配置中每页条目数Paginator直接对传入模板的页面集合分页不能覆盖每页条目数。官方文档给出的Paginate实战示例见 pagination.md{{ $pages : where site.RegularPages Type posts }} {{ $paginator : .Paginate $pages.ByTitle 7 }} {{ range $paginator.Pages }} h2a href{{ .RelPermalink }}{{ .LinkTitle }}/a/h2 {{ end }} {{ partial pagination.html . }}分页配置每页条目数等行为可在项目配置如hugo.toml中设置对应配置键为pagination.pagerSize默认每页 10 条。配置完成后Hugo 会为列表页生成多个分页子页面并通过Paginator自动生成上一页/下一页等导航链接。分页时还需注意同一列表页不应多次调用分页方法否则会产生非预期结果官方文档将其列为最常见的分页模板错误参见 pagination.md。源码级原理列表页的页面集合从何而来从实现层面看列表页模板中的.Pages、.RegularPages等页面集合最终由 Hugo 核心包hugolib构建。在 hugolib/pagecollections.go 中pageFinder结构体持有pageMap引用负责在站点内按引用ref/relRef查找页面节点而页面集合的遍历能力则定义在 resources/page/page.go 的ChildCareProvider接口中Pages()返回所有 kind 的页面列表RegularPages()仅返回 kind 为page的普通页面RegularPagesRecursive()返回当前栏目下所有层级的普通页面对深层嵌套栏目尤其重要。理解这三者的差异是写出正确列表页模板的关键栏目列表页默认只聚合直接子级若要递归聚合后代内容必须显式调用RegularPagesRecursive。这也是 栏目文档 中反复强调的易错点。总结列表页的本质是页面种类 × 页面集合 × 上下文三者的结合home、section、taxonomy、term四种页面种类各自承载特定范围的页面集合并统一由_default/list.html兜底渲染。实战中只需掌握三条主线即可游刃有余判定凡是在上下文中接收到页面集合的页面即为列表页与 single page 在模板路由上天然区分取数根据聚合范围在.Pages、.RegularPages、.RegularPagesRecursive之间正确选择呈现页面集合较大时用Paginate/Paginator分页并注意避免重复分页。参考仓库中的 列表页词条、模板查找顺序、分页指南 以及 pagecollections.go 与 page.go 的源码实现即可在实践中持续加深对 Hugo 列表页机制的理解。赞分享开发工具前端CLI【免费下载链接】hugoThe world’s fastest framework for building websites.项目地址https://gitcode.com/gh_mirrors/hu/hugo点击查看免费下载相关推荐Hugo 模板函数 collections.Group 完全指南按 Key 分组页面集合与分页实战Hugo 模板函数 collections.Group 完全指南按 Key 分组页面集合与分页实战 本指南深入讲解 Hugo 模板函数 collections开发工具前端CLIHugo 模板中 PAGER.Pages 方法详解分页器当前页页面集合的获取与实战Hugo 模板中 PAGER.Pages 方法详解分页器当前页页面集合的获取与实战 导读 PAGER.Pages 是 Hugo 模板系统中分页Paginat开发工具前端CLIHugo 页面方法 Section 完全指南获取页面所属顶层 Section 与页面集合构建实战Hugo 页面方法 Section 完全指南获取页面所属顶层 Section 与页面集合构建实战 导读 .Section 是 Hugo 在 Page 对象上提开发工具前端CLI上一篇FakeLocation入门指南如何为单个App设置虚假GPS位置轻松搞定定位打卡下一篇Home Assistant 本地智能家居快速上手指南零基础 30 分钟到第一个自动化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Hugo 列表页（List Page）完全指南：页面集合、模板选择与分页实战
开发工具前端CLI【免费下载链接】hugoThe world’s fastest framework for building websites.项目地址https://gitcode.com/gh_mirrors/hu/hugo点击查看免费下载列表页list page是 Hugo 站点中负责聚合展示的一类页面它接收一个页面集合page collection作为模板上下文将同类型的页面统一渲染。本文基于 Hugo 官方术语表对列表页的定义结合本仓库源码与官方文档系统讲解列表页的判定标准、四类典型列表页、模板选择机制以及分页实战帮助你精准掌控_default/list.html的编写与扩展。什么是列表页Hugo 官方定义在 Hugo 官方术语表 中list-page词条给出如下定义见 list-page.mdA list page is anypage kindthat receives a pagecollectionincontext. This includes the home page,section pages,taxonomy pages, andterm pages.即列表页是任何在上下文context中接收到页面集合collection的页面种类page kind具体包括首页home page、栏目页section page、分类页taxonomy page和术语页term page四类。这个定义由三个基础术语支撑理解它们是掌握列表页的前提页面种类page kindHugo 对页面的分类取值仅有home、page、section、taxonomy、term五种见 page-kind.md。集合collection即数组array、切片slice或映射map这类可迭代的数据结构见 collection.md。上下文context在模板动作中用点号.表示指当前所处数据结构的位置。例如遍历一个页面集合时每次迭代的上下文就是该页面的数据结构每个模板接收的上下文取决于模板类型及其调用方式见 context.md。五种页面种类中谁是列表页Hugo 将页面划分为五种 kind其中只有page普通页面不是列表页页面种类kind是否列表页上下文内容home✅全站页面集合page❌单篇内容由_default/single.html渲染section✅当前栏目内的页面集合taxonomy✅某分类下的术语term集合term✅拥有某术语的页面集合官方模板文档对此有直接说明页面种类决定了它属于single page普通内容页HTML 输出查找_default/single.html还是list page栏目列表、首页、分类列表、分类术语HTML 输出查找_default/list.html参见 模板查找顺序文档。从源码结构也可以印证这一点在 resources/page/page.go 的ChildCareProvider接口中Pages()返回所有 kind 的页面列表RegularPages()只返回 kind 为page的普通页面而RegularPagesRecursive()返回当前栏目下所有层级的普通页面——这些方法正是列表页模板中获取页面集合的核心入口。四类列表页逐一拆解1. 首页home pagehome是站点的唯一入口页也是列表页中上下文最宽的一类它的页面集合覆盖整个站点的内容。首页模板的典型写法是遍历site.RegularPages或.Pages来输出全站文章列表常与分页配合使用详见下文。2. 栏目页section page栏目页是 kind 为section的页面通常列出当前栏目内的普通页面regular pages和/或其它栏目页见 section-page.md。关于栏目与列表页的关系栏目Sections文档 给出了关键对比目录名会成为 URL 路径段只有栏目含_index.md的目录才有列表页栏目具有逻辑上的祖先与后代关系非栏目目录则没有。文档中还特别强调products 栏目的列表页默认只包含product-1、product-2这类直接子项不包含更深层级的后代页面若希望列出栏目下所有层级的普通页面应在栏目模板中使用RegularPagesRecursive方法而非Pages——这正是 resources/page/page.go 中该方法的接口语义。3. 分类页taxonomy page分类页是 kind 为taxonomy的页面通常列出给定分类taxonomy内的术语terms见 taxonomy-page.md。以 分类Taxonomies文档 中的电影站为例其数据组织层级为Actor - Taxonomy分类 Bruce Willis - Term术语 The Sixth Sense - Value内容 Unbreakable - ValueHugo 会根据内容 front matter 中声明的分类字段自动为每个 Actor、Director、Studio 等生成分类页每个分类页再列出匹配的术语。4. 术语页term page术语页是 kind 为term的页面通常列出拥有某个给定术语的普通页面和栏目页见 term-page.md。沿用上面的例子/actors/bruce-willis/就是一个术语页它的页面集合包含所有在 front matter 中标注了actors: [Bruce Willis]的电影页面。列表页的模板选择查找顺序与命名约定列表页统一使用_default/list.html作为兜底模板但 Hugo 提供了按 kind、layout、输出格式、语言等维度逐级精确匹配的查找机制。以 HTML 输出为例四类列表页的常用模板命名如下列表页类型推荐模板路径全站通用layouts/_default/list.html首页专用layouts/index.html栏目页layouts/_default/section.html或layouts/section/list.html分类页layouts/_default/taxonomy.html术语页layouts/_default/term.html模板查找的完整优先级规则按具体程度从高到低考虑 kind、layout、输出格式、语言、type、section 等参数详见 模板查找顺序文档。其中 kind 是最重要的维度之一Hugo 据此判断是渲染单页还是列表页并决定回退到single.html还是list.html。一个最小可用的列表页模板示例layouts/_default/list.html{{ define main }} h1{{ .Title }}/h1 ul {{ range .Pages }} lia href{{ .RelPermalink }}{{ .LinkTitle }}/a/li {{ end }} /ul {{ end }}其中.Pages即为该列表页上下文中的页面集合若只想列出普通页面可改用.RegularPages若当前是栏目页且需要包含所有后代层级则使用.RegularPagesRecursive。列表页分页Paginate 与 Paginator当列表页承载的页面集合较大时分页Pagination文档 明确指出应优先为home、section、taxonomy、term这四类列表页开启分页以提升可读性与加载性能。分页相关术语paginate动词将列表页拆分为两个或更多子集见 paginate.mdpagination名词对列表页执行分页的过程见 pagination.mdpager分页过程中创建的对象包含列表页的一个子集及指向其它 pager 的导航链接见 pager.md。两种分页方法在列表页模板中可对Page对象调用以下任一方法Paginate更灵活可对任意页面集合分页支持先过滤、排序、分组并可覆盖项目配置中每页条目数Paginator直接对传入模板的页面集合分页不能覆盖每页条目数。官方文档给出的Paginate实战示例见 pagination.md{{ $pages : where site.RegularPages Type posts }} {{ $paginator : .Paginate $pages.ByTitle 7 }} {{ range $paginator.Pages }} h2a href{{ .RelPermalink }}{{ .LinkTitle }}/a/h2 {{ end }} {{ partial pagination.html . }}分页配置每页条目数等行为可在项目配置如hugo.toml中设置对应配置键为pagination.pagerSize默认每页 10 条。配置完成后Hugo 会为列表页生成多个分页子页面并通过Paginator自动生成上一页/下一页等导航链接。分页时还需注意同一列表页不应多次调用分页方法否则会产生非预期结果官方文档将其列为最常见的分页模板错误参见 pagination.md。源码级原理列表页的页面集合从何而来从实现层面看列表页模板中的.Pages、.RegularPages等页面集合最终由 Hugo 核心包hugolib构建。在 hugolib/pagecollections.go 中pageFinder结构体持有pageMap引用负责在站点内按引用ref/relRef查找页面节点而页面集合的遍历能力则定义在 resources/page/page.go 的ChildCareProvider接口中Pages()返回所有 kind 的页面列表RegularPages()仅返回 kind 为page的普通页面RegularPagesRecursive()返回当前栏目下所有层级的普通页面对深层嵌套栏目尤其重要。理解这三者的差异是写出正确列表页模板的关键栏目列表页默认只聚合直接子级若要递归聚合后代内容必须显式调用RegularPagesRecursive。这也是 栏目文档 中反复强调的易错点。总结列表页的本质是页面种类 × 页面集合 × 上下文三者的结合home、section、taxonomy、term四种页面种类各自承载特定范围的页面集合并统一由_default/list.html兜底渲染。实战中只需掌握三条主线即可游刃有余判定凡是在上下文中接收到页面集合的页面即为列表页与 single page 在模板路由上天然区分取数根据聚合范围在.Pages、.RegularPages、.RegularPagesRecursive之间正确选择呈现页面集合较大时用Paginate/Paginator分页并注意避免重复分页。参考仓库中的 列表页词条、模板查找顺序、分页指南 以及 pagecollections.go 与 page.go 的源码实现即可在实践中持续加深对 Hugo 列表页机制的理解。赞分享开发工具前端CLI【免费下载链接】hugoThe world’s fastest framework for building websites.项目地址https://gitcode.com/gh_mirrors/hu/hugo点击查看免费下载相关推荐Hugo 模板函数 collections.Group 完全指南按 Key 分组页面集合与分页实战Hugo 模板函数 collections.Group 完全指南按 Key 分组页面集合与分页实战 本指南深入讲解 Hugo 模板函数 collections开发工具前端CLIHugo 模板中 PAGER.Pages 方法详解分页器当前页页面集合的获取与实战Hugo 模板中 PAGER.Pages 方法详解分页器当前页页面集合的获取与实战 导读 PAGER.Pages 是 Hugo 模板系统中分页Paginat开发工具前端CLIHugo 页面方法 Section 完全指南获取页面所属顶层 Section 与页面集合构建实战Hugo 页面方法 Section 完全指南获取页面所属顶层 Section 与页面集合构建实战 导读 .Section 是 Hugo 在 Page 对象上提开发工具前端CLI上一篇FakeLocation入门指南如何为单个App设置虚假GPS位置轻松搞定定位打卡下一篇Home Assistant 本地智能家居快速上手指南零基础 30 分钟到第一个自动化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考