Minimal Mistakes 分类归档页category-archive配置实战从 Front Matter 到layout: categories的完整实现解析【免费下载链接】minimal-mistakes:triangular_ruler: Jekyll theme for building a personal site, blog, project documentation, or portfolio.项目地址: https://gitcode.com/gh_mirrors/mi/minimal-mistakes本文以 Minimal Mistakes 主题仓库中test/_pages/category-archive.md与docs/_pages/category-archive.md两个同构示例页为切入点系统讲解如何在基于 Jekyll 的个人站点、博客与项目文档站中用最简 Front Matter 搭建一个按分类聚合全部文章的归档页。读完本文你将掌握layout: categories的字段语义、其底层模板categories.html与posts-taxonomy.html的分组排序机制以及列表/网格两种展示形态与配套的 SEO、面包屑等细节配置。一、关联文档定位一个文件即一个完整的分类归档页在 Minimal Mistakes 仓库中分类归档示例页有两个完全同构的副本test/_pages/category-archive.mddocs/_pages/category-archive.md两者内容逐字一致全文仅含 5 行 YAML Front Matter没有任何正文内容--- title: Posts by Category layout: categories permalink: /categories/ author_profile: true ---这意味着按分类归档这个功能完全由 Front Matter 驱动Jekyll 解析完这 5 个键值后交给categories布局渲染页面主体内容则由布局底层的 include 自动生成无需作者手写任何 Markdown。这种零正文模式正是归档页的标准写法因为归档页的全部价值在于对site.categories的自动聚合而非静态文本。在 docs 站点的布局总表中它被登记为名称布局示例源文件Categories Archive全部分类聚合页layout: categoriescategory-archive.md对应地layout: category单分类页与layout: tags/layout: tag构成完整的分类-标签归档体系详见 docs/_docs/10-layouts.md。二、五个 Front Matter 字段逐一拆解1.title页面标题title: Posts by Category会被 archive.html 布局输出为归档区顶部的h1 idpage-title classpage__title。注意归档页的h1默认不含no_toc等抑制类且该idpage-title同时是posts-taxonomy.html中回到顶部锚点的跳转目标见下文分组小节。2.layout: categories决定渲染逻辑的核心这是归档页的灵魂。layout: categories指向 _layouts/categories.html其完整内容为--- layout: archive --- {%- assign locale page.locale | default: layout.locale | default: site.locale %} {{ content }} {% include posts-taxonomy.html localelocale taxonomiessite.categories %}三个要点继承archive布局categories布局的layout: archive让它复用归档通用外壳——侧边栏sidebar.html、面包屑breadcrumbs.html、页面 Hero 与div classarchive容器见 _layouts/archive.html。因此分类归档页支持与layout: archive相同的 Front Matter官方文档原话见 docs/_docs/10-layouts.md例如header、sidebar、breadcrumbs、locale等均可用。locale 解析链page.locale | default: layout.locale | default: site.locale支持按页面粒度覆盖 UI 文案语言最终传入posts-taxonomy.html。数据源是全局的site.categoriesJekyll 会把所有文章categories字段聚合为site.categories一个分类名 → 文章数组的哈希include 将其作为taxonomies传入。3.permalink: /categories/固定链接将归档页固定输出到站点根下的/categories/路径在本地预览时为http://localhost:4000/categories/。固定 permalink 的好处是便于在导航_data/navigation.yml、页脚、文章内链中稳定引用。docs 站点的分类归档就挂在/categories/同时示例还有一个/categories-grid/网格变体见后文。4.author_profile: true开启作者侧边栏该字段在布局中被显式关闭过吗注意 _layouts/archive-taxonomy.html 的 Front Matter 里有author_profile: false的默认值但categories布局并未设置因此页面级author_profile: true生效归档页右侧会渲染作者资料卡author-profile.html包含头像、简介与社交链接。如果你希望归档页更聚焦内容可将其改为author_profile: false。三、底层实现posts-taxonomy.html 的分组、排序与锚点机制分类归档的真正渲染发生在 _includes/posts-taxonomy.html它被categories布局传site.categories和tags布局传site.tags共用是一份通用的税则分组实现。其算法分两段第一段求最大分组尺寸用于倒序索引{% assign items_max 0 %} {% for item in include.taxonomies %} {% if item[1].size items_max %} {% assign items_max item[1].size %} {% endif %} {% endfor %}先遍历所有分类找出文章数最多的那个分类得到items_max。第二段按文章数从多到少渲染索引与分组区块ul classtaxonomy__index {% for i in (1..items_max) reversed %} {% for item in include.taxonomies %} {% if item[1].size i %} li a href#{{ item[0] | slugify }} strong{{ item[0] }}/strong span classtaxonomy__count{{ i }}/span /a /li {% endif %} {% endfor %} {% endfor %} /ul外层循环(1..items_max) reversed表示从最大数量递减内层循环对每个分类做文章数 i的匹配从而让文章最多的分类排在最前实现按热门度降序每个索引项是锚点链接#分类名(slugify 后)span classtaxonomy__count显示该分类的文章数。随后是真正的分组区块同样按数量降序{% assign entries_layout page.entries_layout | default: list %} {% for i in (1..items_max) reversed %} {% for taxonomy in include.taxonomies %} {% if taxonomy[1].size i %} section id{{ taxonomy[0] | slugify }} classtaxonomy__section h2 classarchive__subtitle{{ taxonomy[0] }}/h2 div classentries-{{ entries_layout }} {% for post in taxonomy.last %} {% include archive-single.html localelocale typeentries_layout %} {% endfor %} /div a href#page-title classback-to-top{{ site.data.ui-text[locale].back_to_top | default: Back to Top }} uarr;/a /section {% endif %} {% endfor %} {% endfor %}可验证的实现要点每个分类渲染为一个section id分类-slug标题h2.archive__subtitle即分类名区块内逐篇渲染文章条目条目组件是 archive-single.html输出标题链接、日期等元信息page__meta.html与截断至 160 字符的摘要post.excerpt | truncate: 160每个区块末尾是回到顶部链接锚点指向归档页h1的idpage-title文案从 _data/ui-text.yml 按locale读取默认 Back to Top支持多语言覆盖注意排序差异layout: categories全局聚合按分类内文章数降序而单分类页layout: category使用 posts-category.html后者仅site.categories[include.taxonomy]过滤并额外过滤hidden ! true的文章文章顺序遵循 Jekyll 默认按日期逆序不涉及数量排序。四、列表与网格两种展示形态归档页默认以列表list呈现。若想切换为网格卡片只需在 Front Matter 增加entries_layout: grid仓库在 test 目录就内置了对应示例 test/_pages/category-archive-grid.md--- title: Posts by Category (grid view) layout: categories permalink: /categories-grid/ entries_layout: grid author_profile: true ---entries_layout的取值在 posts-taxonomy.html 中读取默认回退为list可选list或grid在grid模式下archive-single.html 会额外渲染post.header.teaser或全局site.teaser作为缩略图没有 teaser 时则只输出文字卡片官方文档亦注明默认文档以列表视图展示如需网格视图请在页面 Front Matter 中加入entries_layout: griddocs/_docs/10-layouts.md。五、配套配置分类数据从哪来分类归档页本身不产生分类它聚合的是所有文章 Front Matter 中的categories字段。以 test 站点的边界用例 test/_posts/2009-07-02-edge-case-many-categories.md 为例--- title: Edge Case: Many Categories categories: - aciform - antiquarianism - arrangement - asmodeus - broder - buying - championship - chastening - disinclination - disinfection - dispatch - echappee ---一篇文章可归属多个分类Jekyll 会将它们全部并入site.categories归档页据此为每个分类生成索引与分组区块。实战建议在_config.yml中为文章统一设置归档友好的默认值参考 docs/_docs/11-posts.md 给出的推荐配置defaults: # _posts - scope: path: type: posts values: layout: single author_profile: true read_time: true comments: true share: true related: true配合给每篇文章书写唯一的excerpt归档页摘要与 SEO 都依赖它即可获得信息密度高、可读性强的分类归档页。六、归档页如何加入站点导航归档页写好后将其加入导航即可让访客触达。参考仓库根 _data/navigation.yml 与 docs/_data/navigation.yml 的条目写法main: - title: Categories url: /categories/url与归档页permalink: /categories/严格对应避免出现指向不存在路径的死链。七、与单分类页、标签归档的体系对照为了让读者明确category-archive.md在整套归档体系中的位置对照 docs 文档docs/_docs/10-layouts.md整理如下需求布局关键 Front Matter全部分类聚合本文主角categoriespermalink、可选entries_layout单个分类下的文章categorytaxonomy: 分类名、entries_layout全部标签聚合tags同categories单个标签下的文章tagtaxonomy: 标签名、entries_layout按年份聚合posts同archive集合文档聚合collectioncollection、sort_by、sort_order等单分类页的最小写法taxonomy指向分类名--- title: Foo layout: category permalink: /categories/foo/ taxonomy: foo ---如果站点启用了jekyll-archives插件也可直接在_config.yml的 Archive Settings 中声明式生成分类页免去手写页面文件docs/_docs/05-configuration.md 中的 Archive Settings 一节。但手写页面本主题不依赖任何插件在 GitHub Pages 等受限环境同样可用这也是它被官方保留为示例源码的原因。八、结语五行业务字段一个完整功能回看category-archive.md的完整形态——title、layout: categories、permalink、author_profile外加可选的entries_layout——它的简洁是建立在 Minimal Mistakes 主题分层架构之上的archive布局提供页面骨架categories布局注入分组逻辑posts-taxonomy.html完成分组、降序索引与区块渲染archive-single.html负责单篇条目的卡片/列表输出。理解这条调用链后你不仅能照抄示例搭建分类归档页还能按需改造调整排序策略、定制条目模板、增加 locale 文案将归档能力无缝融入自己的 Jekyll 站点。【免费下载链接】minimal-mistakes:triangular_ruler: Jekyll theme for building a personal site, blog, project documentation, or portfolio.项目地址: https://gitcode.com/gh_mirrors/mi/minimal-mistakes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Minimal Mistakes 分类归档页（category-archive）配置实战：从 Front Matter 到 `layout: categories` 的完整实现解析
Minimal Mistakes 分类归档页category-archive配置实战从 Front Matter 到layout: categories的完整实现解析【免费下载链接】minimal-mistakes:triangular_ruler: Jekyll theme for building a personal site, blog, project documentation, or portfolio.项目地址: https://gitcode.com/gh_mirrors/mi/minimal-mistakes本文以 Minimal Mistakes 主题仓库中test/_pages/category-archive.md与docs/_pages/category-archive.md两个同构示例页为切入点系统讲解如何在基于 Jekyll 的个人站点、博客与项目文档站中用最简 Front Matter 搭建一个按分类聚合全部文章的归档页。读完本文你将掌握layout: categories的字段语义、其底层模板categories.html与posts-taxonomy.html的分组排序机制以及列表/网格两种展示形态与配套的 SEO、面包屑等细节配置。一、关联文档定位一个文件即一个完整的分类归档页在 Minimal Mistakes 仓库中分类归档示例页有两个完全同构的副本test/_pages/category-archive.mddocs/_pages/category-archive.md两者内容逐字一致全文仅含 5 行 YAML Front Matter没有任何正文内容--- title: Posts by Category layout: categories permalink: /categories/ author_profile: true ---这意味着按分类归档这个功能完全由 Front Matter 驱动Jekyll 解析完这 5 个键值后交给categories布局渲染页面主体内容则由布局底层的 include 自动生成无需作者手写任何 Markdown。这种零正文模式正是归档页的标准写法因为归档页的全部价值在于对site.categories的自动聚合而非静态文本。在 docs 站点的布局总表中它被登记为名称布局示例源文件Categories Archive全部分类聚合页layout: categoriescategory-archive.md对应地layout: category单分类页与layout: tags/layout: tag构成完整的分类-标签归档体系详见 docs/_docs/10-layouts.md。二、五个 Front Matter 字段逐一拆解1.title页面标题title: Posts by Category会被 archive.html 布局输出为归档区顶部的h1 idpage-title classpage__title。注意归档页的h1默认不含no_toc等抑制类且该idpage-title同时是posts-taxonomy.html中回到顶部锚点的跳转目标见下文分组小节。2.layout: categories决定渲染逻辑的核心这是归档页的灵魂。layout: categories指向 _layouts/categories.html其完整内容为--- layout: archive --- {%- assign locale page.locale | default: layout.locale | default: site.locale %} {{ content }} {% include posts-taxonomy.html localelocale taxonomiessite.categories %}三个要点继承archive布局categories布局的layout: archive让它复用归档通用外壳——侧边栏sidebar.html、面包屑breadcrumbs.html、页面 Hero 与div classarchive容器见 _layouts/archive.html。因此分类归档页支持与layout: archive相同的 Front Matter官方文档原话见 docs/_docs/10-layouts.md例如header、sidebar、breadcrumbs、locale等均可用。locale 解析链page.locale | default: layout.locale | default: site.locale支持按页面粒度覆盖 UI 文案语言最终传入posts-taxonomy.html。数据源是全局的site.categoriesJekyll 会把所有文章categories字段聚合为site.categories一个分类名 → 文章数组的哈希include 将其作为taxonomies传入。3.permalink: /categories/固定链接将归档页固定输出到站点根下的/categories/路径在本地预览时为http://localhost:4000/categories/。固定 permalink 的好处是便于在导航_data/navigation.yml、页脚、文章内链中稳定引用。docs 站点的分类归档就挂在/categories/同时示例还有一个/categories-grid/网格变体见后文。4.author_profile: true开启作者侧边栏该字段在布局中被显式关闭过吗注意 _layouts/archive-taxonomy.html 的 Front Matter 里有author_profile: false的默认值但categories布局并未设置因此页面级author_profile: true生效归档页右侧会渲染作者资料卡author-profile.html包含头像、简介与社交链接。如果你希望归档页更聚焦内容可将其改为author_profile: false。三、底层实现posts-taxonomy.html 的分组、排序与锚点机制分类归档的真正渲染发生在 _includes/posts-taxonomy.html它被categories布局传site.categories和tags布局传site.tags共用是一份通用的税则分组实现。其算法分两段第一段求最大分组尺寸用于倒序索引{% assign items_max 0 %} {% for item in include.taxonomies %} {% if item[1].size items_max %} {% assign items_max item[1].size %} {% endif %} {% endfor %}先遍历所有分类找出文章数最多的那个分类得到items_max。第二段按文章数从多到少渲染索引与分组区块ul classtaxonomy__index {% for i in (1..items_max) reversed %} {% for item in include.taxonomies %} {% if item[1].size i %} li a href#{{ item[0] | slugify }} strong{{ item[0] }}/strong span classtaxonomy__count{{ i }}/span /a /li {% endif %} {% endfor %} {% endfor %} /ul外层循环(1..items_max) reversed表示从最大数量递减内层循环对每个分类做文章数 i的匹配从而让文章最多的分类排在最前实现按热门度降序每个索引项是锚点链接#分类名(slugify 后)span classtaxonomy__count显示该分类的文章数。随后是真正的分组区块同样按数量降序{% assign entries_layout page.entries_layout | default: list %} {% for i in (1..items_max) reversed %} {% for taxonomy in include.taxonomies %} {% if taxonomy[1].size i %} section id{{ taxonomy[0] | slugify }} classtaxonomy__section h2 classarchive__subtitle{{ taxonomy[0] }}/h2 div classentries-{{ entries_layout }} {% for post in taxonomy.last %} {% include archive-single.html localelocale typeentries_layout %} {% endfor %} /div a href#page-title classback-to-top{{ site.data.ui-text[locale].back_to_top | default: Back to Top }} uarr;/a /section {% endif %} {% endfor %} {% endfor %}可验证的实现要点每个分类渲染为一个section id分类-slug标题h2.archive__subtitle即分类名区块内逐篇渲染文章条目条目组件是 archive-single.html输出标题链接、日期等元信息page__meta.html与截断至 160 字符的摘要post.excerpt | truncate: 160每个区块末尾是回到顶部链接锚点指向归档页h1的idpage-title文案从 _data/ui-text.yml 按locale读取默认 Back to Top支持多语言覆盖注意排序差异layout: categories全局聚合按分类内文章数降序而单分类页layout: category使用 posts-category.html后者仅site.categories[include.taxonomy]过滤并额外过滤hidden ! true的文章文章顺序遵循 Jekyll 默认按日期逆序不涉及数量排序。四、列表与网格两种展示形态归档页默认以列表list呈现。若想切换为网格卡片只需在 Front Matter 增加entries_layout: grid仓库在 test 目录就内置了对应示例 test/_pages/category-archive-grid.md--- title: Posts by Category (grid view) layout: categories permalink: /categories-grid/ entries_layout: grid author_profile: true ---entries_layout的取值在 posts-taxonomy.html 中读取默认回退为list可选list或grid在grid模式下archive-single.html 会额外渲染post.header.teaser或全局site.teaser作为缩略图没有 teaser 时则只输出文字卡片官方文档亦注明默认文档以列表视图展示如需网格视图请在页面 Front Matter 中加入entries_layout: griddocs/_docs/10-layouts.md。五、配套配置分类数据从哪来分类归档页本身不产生分类它聚合的是所有文章 Front Matter 中的categories字段。以 test 站点的边界用例 test/_posts/2009-07-02-edge-case-many-categories.md 为例--- title: Edge Case: Many Categories categories: - aciform - antiquarianism - arrangement - asmodeus - broder - buying - championship - chastening - disinclination - disinfection - dispatch - echappee ---一篇文章可归属多个分类Jekyll 会将它们全部并入site.categories归档页据此为每个分类生成索引与分组区块。实战建议在_config.yml中为文章统一设置归档友好的默认值参考 docs/_docs/11-posts.md 给出的推荐配置defaults: # _posts - scope: path: type: posts values: layout: single author_profile: true read_time: true comments: true share: true related: true配合给每篇文章书写唯一的excerpt归档页摘要与 SEO 都依赖它即可获得信息密度高、可读性强的分类归档页。六、归档页如何加入站点导航归档页写好后将其加入导航即可让访客触达。参考仓库根 _data/navigation.yml 与 docs/_data/navigation.yml 的条目写法main: - title: Categories url: /categories/url与归档页permalink: /categories/严格对应避免出现指向不存在路径的死链。七、与单分类页、标签归档的体系对照为了让读者明确category-archive.md在整套归档体系中的位置对照 docs 文档docs/_docs/10-layouts.md整理如下需求布局关键 Front Matter全部分类聚合本文主角categoriespermalink、可选entries_layout单个分类下的文章categorytaxonomy: 分类名、entries_layout全部标签聚合tags同categories单个标签下的文章tagtaxonomy: 标签名、entries_layout按年份聚合posts同archive集合文档聚合collectioncollection、sort_by、sort_order等单分类页的最小写法taxonomy指向分类名--- title: Foo layout: category permalink: /categories/foo/ taxonomy: foo ---如果站点启用了jekyll-archives插件也可直接在_config.yml的 Archive Settings 中声明式生成分类页免去手写页面文件docs/_docs/05-configuration.md 中的 Archive Settings 一节。但手写页面本主题不依赖任何插件在 GitHub Pages 等受限环境同样可用这也是它被官方保留为示例源码的原因。八、结语五行业务字段一个完整功能回看category-archive.md的完整形态——title、layout: categories、permalink、author_profile外加可选的entries_layout——它的简洁是建立在 Minimal Mistakes 主题分层架构之上的archive布局提供页面骨架categories布局注入分组逻辑posts-taxonomy.html完成分组、降序索引与区块渲染archive-single.html负责单篇条目的卡片/列表输出。理解这条调用链后你不仅能照抄示例搭建分类归档页还能按需改造调整排序策略、定制条目模板、增加 locale 文案将归档能力无缝融入自己的 Jekyll 站点。【免费下载链接】minimal-mistakes:triangular_ruler: Jekyll theme for building a personal site, blog, project documentation, or portfolio.项目地址: https://gitcode.com/gh_mirrors/mi/minimal-mistakes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考