Minimal Mistakes 目录缩进实战：用 toc 与嵌套标题构建多级 Table of Contents-平芜编程栈

前端
静态站点

【免费下载链接】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 主题仓库中的示例文章 layout-table-of-contents-indent-post.md 为骨架，完整讲解如何在博文与页面中启用 Table of Contents（目录）、控制其标题与图标、以及当正文出现 H1~H6 多级嵌套标题时，目录缩进层级与可读性的真实行为。读完你将掌握toc系列 Front Matter 配置、主题内部生成目录的源码链路，以及如何借助 kramdown 的toc_levels与 SCSS 缩进规则调校目录展示。

一、示例文章的作用：验证多级目录的缩进可读性

在 Minimal Mistakes 的 docs 示例集中，存在一组专门用于测试目录功能的文章：

layout-table-of-contents-post.md：验证单级/浅层目录，并演示toc_label与toc_icon的用法；
layout-table-of-contents-indent-post.md：本篇关联文档，正文刻意编排了从 H1 一路嵌套到 H6 的标题层级，目的是“Tests table of contents with multiple levels to verify indentation is readible”（测试多级目录以验证缩进可读性）；
layout-table-of-contents-include-post.md 与 layout-table-of-contents-sticky.md：分别演示{% include toc %}手动引入与toc_sticky吸顶目录。

本文关联文档的前置元数据非常简单：

--- title: "Layout: Post with Nested Table of Contents" tags: - table of contents toc: true ---

可见核心开关只有一个：toc: true。正文随后抛出了大量#、##、###、####、#####、######标题，形成形如2.1.1.1.1、3.5.1.1.1的多级编号树，用于检验目录在五到六层嵌套时仍能通过缩进清晰区分层级关系。

二、目录开关与定制：toc / toc_label / toc_icon / toc_sticky

以 layout-table-of-contents-post.md 的 Front Matter 为例，完整的目录配置如下：

--- title: "Layout: Post with Table of Contents" tags: - table of contents toc: true toc_label: "Unique Title" toc_icon: "heart" ---

四个配置项的含义与取值说明：

配置项	作用	默认值	取值示例
`toc`	是否在正文旁渲染目录侧栏	`false`	`true`/`false`
`toc_label`	目录栏标题文字	读取`_data/ui-text.yml`中的`toc_label`（英文默认 "On this page"），再兜底为 "On this page"	`"Unique Title"`、`"目录"`
`toc_icon`	目录栏标题左侧的 Font Awesome 图标名（不带`fa-`前缀）	`file-alt`	`heart`、`list-ul`、`book`
`toc_sticky`	目录栏是否随页面滚动吸顶	`false`	`true`/`false`（参见 layout-table-of-contents-sticky.md）

其中toc_label的默认文案在 ui-text.yml 中定义为：

toc_label : "On this page"

该文件同时提供多语言翻译键，可在站点级覆盖。图标名对应的 Font Awesome 类名拼装方式见下文源码分析。

三、目录是如何生成的：从 Front Matter 到 HTML 的调用链

3.1 布局层的渲染入口

启用toc: true后，目录由 single.html（single布局）在正文之前渲染：

{% if page.toc %} <aside class="sidebar__right {% if page.toc_sticky %}sticky{% endif %}"> <nav class="toc" aria-label="Table of contents"> <header><h4 class="nav__title"><i class="fas fa-{{ page.toc_icon | default: 'file-alt' }}"></i> {{ page.toc_label | default: site.data.ui-text[locale].toc_label | default: "On this page" }}</h4></header> {% include toc.html sanitize=true html=content h_min=1 h_max=6 class="toc__menu" skip_no_ids=true %} </nav> </aside> {% endif %}

可以清楚看到三件事：

toc_icon被拼进fas fa-前缀的<i>标签（默认file-alt），toc_label依次回退到site.data.ui-text[locale].toc_label与硬编码的 "On this page"；
目录内容来自对 kramdown 编译后content的二次解析，而不是 Jekyll 原生功能；
若toc_sticky: true，aside会追加sticky类。

3.2 底层解析器：jekyll-toc 的 toc.html

目录真正的生成逻辑在 _includes/toc.html，这是被广泛使用的开源 Liquid 组件 jekyll-toc（版本 1.2.1）。它通过字符串切分解析content中所有<h1>~<h6>标签，并支持下列参数（主题在single.html中使用的取值已标注）：

参数	默认值	主题传值	说明
`html`	必填	`content`	kramdown 编译后的页面 HTML
`sanitize`	`false`	`true`	目录条目去除标题内嵌 HTML，仅保留纯文本
`h_min`	`1`	`1`	纳入目录的最小标题层级
`h_max`	`6`	`6`	纳入目录的最大标题层级
`class`	`''`	`toc__menu`	输出列表的 CSS 类
`skip_no_ids`	`false`	`true`	跳过没有`id`属性的标题（正文标题需能生成锚点）
`ordered`	`false`	—	输出有序列表
`flat_toc`	`false`	—	扁平单层列表
`item_class`/`submenu_class`	`''`	—	为列表项/子菜单追加自定义类，支持`%level%`占位符

核心逻辑要点（见 toc.html）：

将html按<h切分，逐个读取标题级别、id与class；
标题带no_toc类时被跳过——这正是 archive-single.html 中卡片标题使用no_toc类避免污染目录的原因；
通过比较当前标题级别与上一个标题级别，动态生成嵌套的<ul>/<li>结构（currLevel > lastLevel时开新子列表，<时关闭），从而在 HTML 层面天然形成多级缩进树。

3.3 锚点 ID 从哪来

目录链接需要每个标题具备稳定的id锚点。这一能力来自_config.yml中 kramdown 的配置（见 _config.yml）：

kramdown: input: GFM auto_ids: true toc_levels: 1..6

auto_ids: true：为每个标题自动生成id（如#enim-laboris-id-ea-elit-elit-deserunt），这是目录锚点可用的前提；
toc_levels: 1..6：允许自动生成锚点与目录参与的范围，主题默认放开到 6 级，与toc.html的h_max=6一致。

四、缩进层级是如何呈现的：SCSS 的逐级 padding 规则

主题对目录缩进的可读性并非交给浏览器默认样式，而是在 _navigation.scss 中显式定义。.toc侧栏本身具有边框、圆角与阴影；.toc__menu是无符号列表，其链接为块级元素。逐级缩进通过嵌套选择器的padding-inline-start递增实现：

li ul > li a { padding-inline-start: 1.25rem; } li ul li ul > li a { padding-inline-start: 1.75rem; } li ul li ul li ul > li a { padding-inline-start: 2.25rem; } li ul li ul li ul li ul > li a { padding-inline-start: 2.75rem; } li ul li ul li ul li ul li ul > li a { padding-inline-start: 3.25rem; }

也就是说，从第三层开始每深入一层增加约 0.5rem 缩进，最深支持到第六层（3.25rem）。这就是“嵌套目录缩进可读性”在样式层的答案：无论正文标题嵌套到几级，目录都会按层级逐级右移，同时子级链接的字重降为font-weight: normal以弱化视觉权重（navigation.scss）。

此外，滚动监听（scrollspy）会为当前聚焦的目录项添加.active类，其配色由@include yiq-contrasted($active-color)计算（见 navigation.scss）；在打印场景下，print.scss 会将.toc隐藏，避免纸质输出携带导航冗余。

五、复现示例：在自己的站点启用多级目录

要在自己的 Minimal Mistakes 站点复现与本文关联文档相同的效果，只需三步：

确认正文标题层级丰富：在_posts/下新建文章，正文使用##、###、####等多级标题（#通常留给页面/文章主标题），如示例中2.1.1.1.1这种五到六级嵌套；
Front Matter 开启目录：

--- layout: single title: "我的多级目录示例" toc: true toc_label: "本页目录" toc_icon: "list-ul" ---

本地构建验证：在仓库根目录执行bundle exec jekyll serve后访问对应页面，观察右侧目录是否随标题层级逐级缩进；若目录未出现，请依次检查：页面layout是否为single（目录渲染逻辑位于single布局）、toc: true是否写入 Front Matter、以及auto_ids是否被关闭（锚点缺失会导致skip_no_ids=true跳过全部标题）。

常见问题速查：

目录不出现在归档页/首页：目录只由single布局渲染，home、archive等布局不含该逻辑；
想排除某些标题：给标题加{: .no_toc}类，toc.html会跳过带no_toc类的节点；
想调整缩进幅度：修改 _navigation.scss 中各层padding-inline-start的值（注意此为主题源码，建议通过主题覆盖机制在站点侧覆写，而非直接改动主题文件）。

六、小结

启用目录只需toc: true，定制标题与图标使用toc_label、toc_icon，吸顶使用toc_sticky；
目录生成链路为：single.html判断page.toc→ 调用 _includes/toc.html（jekyll-toc）解析 kramdown 输出的<h1>~<h6>→ 按标题级别嵌套<ul>/<li>→ 由 _navigation.scss 的逐级padding-inline-start呈现缩进；
锚点与层级范围依赖 kramdown 的auto_ids: true与toc_levels: 1..6（_config.yml）；
缩进最深支持六层（1.25rem → 3.25rem），打印时目录自动隐藏（_print.scss）。