企业官网建设流程全解析

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.md
• docs/_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 站点的布局总表中，它被登记为：

对应地，layout: category（单分类页）与layout: tags/layout: tag构成完整的分类-标签归档体系，详见 docs/_docs/10-layouts.md。

二、五个 Front Matter 字段逐一拆解

1.title：页面标题

title: "Posts by Category"会被 archive.html 布局输出为归档区顶部的<h1 id="page-title" class="page__title">。注意归档页的h1默认不含no_toc等抑制类，且该id="page-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 locale=locale taxonomies=site.categories %}

三个要点：

1. 继承archive布局：categories布局的layout: archive让它复用归档通用外壳——侧边栏（sidebar.html）、面包屑（breadcrumbs.html）、页面 Hero 与<div class="archive">容器（见 _layouts/archive.html）。因此"分类归档页支持与layout: archive相同的 Front Matter"（官方文档原话，见 docs/_docs/10-layouts.md），例如header、sidebar、breadcrumbs、locale等均可用。
2. locale 解析链：page.locale | default: layout.locale | default: site.locale，支持按页面粒度覆盖 UI 文案语言，最终传入posts-taxonomy.html。
3. 数据源是全局的site.categories：Jekyll 会把所有文章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 class="taxonomy__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 class="taxonomy__count">{{ i }}</span> </a> </li> {% endif %} {% endfor %} {% endfor %} </ul>

• 外层循环(1..items_max) reversed表示从最大数量递减；
• 内层循环对每个分类做"文章数 == i"的匹配，从而让文章最多的分类排在最前，实现按热门度降序；
• 每个索引项是锚点链接#分类名(slugify 后)，<span class="taxonomy__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 }}" class="taxonomy__section"> <h2 class="archive__subtitle">{{ taxonomy[0] }}</h2> <div class="entries-{{ entries_layout }}"> {% for post in taxonomy.last %} {% include archive-single.html locale=locale type=entries_layout %} {% endfor %} </div> <a href="#page-title" class="back-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的id="page-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: grid"（docs/_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）整理如下：

单分类页的最小写法（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