minimal-mistakes 主题下的嵌套与混合列表Edge CaseMarkdown 渲染实战【免费下载链接】minimal-mistakes:triangular_ruler: Jekyll theme for building a personal site, blog, project documentation, or portfolio.项目地址: https://gitcode.com/gh_mirrors/mi/minimal-mistakes本篇指南以仓库中的 edge-case-nested-and-mixed-lists.md 为核心讲解在 minimal-mistakes 主题中编写多层嵌套、有序/无序混合列表及 GitHub 任务列表Task Lists时需要注意的 Markdown 缩进规则、编号行为与样式表现。读完本文你将掌握四类混合列表结构的标准写法、为什么嵌套不会打乱外层有序编号的底层原理以及主题 SCSS 源码中对深层列表与任务列表的具体样式实现可直接套用到自己的博客或文档站点中。一、这篇 Edge Case 文章在验证什么在 Markdown 中列表嵌套是最容易“翻车”的语法之一缩进多一个空格或少一个空格渲染结果就可能从嵌套列表退化成普通段落。这篇 Edge Case 文章正是为此准备的回归测试样例其核心验证目标用文档原话概括为两点列表中的列表不会破坏有序列表的编号顺序Lists within lists do not break the ordered list numbering order列表样式要能覆盖足够深的嵌套层级Your list styles go deep enough。从文章 Front Matter 可以看到它被归入Edge Case分类并带有content、css、edge case、lists、markup等标签title: Edge Case: Nested and Mixed Lists categories: - Edge Case tags: - content - css - edge case - lists - markup这些分类与标签会由主题的分类/标签归档系统见 _config.yml 中的category_archive与tag_archive配置自动归集因此这类 Edge Case 文章同时也是主题排版样式的可视化验收样本。值得注意的是同一篇文章在 docs/_posts/2009-05-15-edge-case-nested-and-mixed-lists.md文档演示站与 test/_posts/2009-05-15-edge-case-nested-and-mixed-lists.md测试站各有一份副本其中测试副本额外补充了嵌套任务列表用例覆盖面更完整。二、四类混合列表结构与缩进规则文档用四个小节分别验证“有序 ↔ 无序”交叉嵌套的四种排列组合。下面逐一给出原文用例并说明其缩进要点。1. 有序 -- 无序 -- 有序1. ordered item 2. ordered item * **unordered** * **unordered** 1. ordered item 2. ordered item 3. ordered item 4. ordered item缩进要点外层2.之后的内容行缩进 3 个空格*形成第一层无序嵌套无序项下再缩进 5 个空格1.形成第二层有序嵌套。最终外层编号仍按1 → 2 → 3 → 4连续推进。2. 有序 -- 无序 -- 无序1. ordered item 2. ordered item * **unordered** * **unordered** * unordered item * unordered item 3. ordered item 4. ordered item缩进要点第一层缩进 3 个空格第二层缩进 5 个空格。注意测试站副本test/_posts/2009-05-15-edge-case-nested-and-mixed-lists.md中该小节用的是 2/4 空格缩进两版缩进不同但均能正确渲染——这印证了 kramdown 对缩进宽度有一定容错只要嵌套内容相对父项内容起点缩进足够即可。3. 无序 -- 有序 -- 无序* unordered item * unordered item 1. ordered 2. ordered * unordered item * unordered item * unordered item * unordered item缩进要点无序项下第一层缩进 3 个空格转为有序列表第二层缩进 5 个空格转回无序。4. 无序 -- 无序 -- 有序* unordered item * unordered item * unordered * unordered 1. **ordered item** 2. **ordered item** * unordered item * unordered item缩进要点第一层缩进 2 个空格第二层缩进 5 个空格内层有序项用加粗强调文字以验证深层文本样式。通用规则小结无论哪层嵌套核心原则都是“子列表内容的缩进必须大于父列表项内容起点”。只要满足这一条件有序/无序可以任意交替嵌套kramdown 会按缩进层级生成正确的 HTML 结构。三、为什么嵌套不会打乱外层编号源码级原理文档开篇断言“嵌套列表不会破坏有序列表编号顺序”。这个结论背后的实现事实是kramdown 在渲染时会把每一层嵌套生成为独立的ol/ul元素内层列表作为外层li的子元素存在而不是与父级ol共享同一个计数器。外层ol只统计自己的直接li因此无论第 2 项内部嵌了多少层列表外层编号依然按1、2、3、4连续递增内层新开的ol会从1重新编号这是 HTML 列表的标准行为这在文档的“有序 -- 无序 -- 有序”用例中表现得最为直观内层有序项同样从1开始。从主题样式看_sass/minimal-mistakes/_base.scss 中为列表定义了垂直节奏ul li, ol li { margin-bottom: 0.5em; } li ul, li ol { margin-top: 0.5em; }也就是说每个li底部留出0.5em间距同时嵌套子列表与其父项之间额外增加0.5em顶部间距保证多层级列表在视觉上层次分明、不会粘连。此外 _sass/minimal-mistakes/_reset.scss 统一了ul/ol的默认外边距_sass/minimal-mistakes/_print.scss 也专门处理了打印场景下的ul/ol样式——这正是文档所说“列表样式要能覆盖足够深的层级”的样式侧保障。对于更深层级的导航类列表_sass/minimal-mistakes/_navigation.scss 中甚至通过li ul li a、li ul li ul li a一直到li ul li ul li ul li ul li ul li a的逐层选择器为最多 5 层嵌套都定义了缩进与边框样式可作为主题“深层级列表也能被样式覆盖”的旁证。四、Task ListsGitHub 风格任务列表文档最后一节是任务列表用例- [x] Finish my changes - [ ] Push my commits to GitHub - [ ] Open a pull request- [x]表示已完成、- [ ]表示未完成。任务列表属于 GitHub Flavored MarkdownGFM扩展语法minimal-mistakes 之所以支持它是因为 _config.yml 中的 kramdown 配置启用了 GFM 输入模式markdown: kramdown kramdown: input: GFM auto_ids: true ...在input: GFM模式下kramdown 会将- [x]/- [ ]转换为一组带特殊 class 的 HTML列表容器获得task-list类每个列表项获得task-list-item类复选框则是task-list-item-checkbox类型的input。主题在 _sass/minimal-mistakes/_utilities.scss 中为这套结构专门定义了样式.task-list { padding: 0; li { list-style-type: none; } .task-list-item-checkbox { margin-inline-end: 0.5em; opacity: 1; } } .task-list .task-list { margin-inline-start: 1em; }要点解读任务列表去除默认的项目符号list-style-type: none与内边距因为勾选框本身已经承担了“标记”职能复选框右侧留出0.5em间距并保持完全不透明opacity: 1保证在浅色/深色皮肤下都清晰可读margin-inline-start: 1em这一条正是为嵌套任务列表准备的它让嵌套的任务列表相对父任务项右缩进1em。测试站副本在任务列表里补充了嵌套用例- [x] Finish my changes - [ ] Push my commits to GitHub - [ ] Open a pull request - [ ] Follow discussions - [x] Push new commits这正是对“任务列表也能多层嵌套”的验证与_utilities.scss中.task-list .task-list的缩进规则一一对应。需要注意的是无论在哪一层任务列表项与其子任务列表之间同样要满足第二节归纳的缩进原则。五、如何在本仓库中复现与验证该 Edge Case 文章同时存在于两处均可直接作为验证样本文档演示站docs/_posts/2009-05-15-edge-case-nested-and-mixed-lists.md测试站test/_posts/2009-05-15-edge-case-nested-and-mixed-lists.md两站各自携带独立的Gemfile与_config.yml。进入对应目录后安装依赖并启动本地预览即可看到渲染结果bundle install bundle exec jekyll serve --livereload根据 _config.yml 的defaults配置所有posts类型默认使用layout: single正文由 _layouts/single.html 中的page__content区域直接输出{{ content }}因此列表渲染完全取决于 Markdown 解析器kramdown GFM与全局 SCSS不依赖任何 JS 脚本。这也是该用例能纯粹验证“列表语法 样式深度”的原因。六、实战建议小结缩进统一优先虽然 kramdown 对缩进宽度有一定容错文档版 3/5 空格、测试版 2/4 空格都能渲染但同一篇文档内建议固定使用一致的缩进宽度避免层级歧义编号不必手动续写嵌套有序列表会自动从 1 重新编号外层编号不受内层影响无需也不应该手写3.、4.之外的序号任务列表依赖 GFM确保_config.yml中kramdown.input: GFM未被修改否则- [x]语法会退化为普通列表项文本深层级列表放心嵌套主题基础样式_base.scss与工具类_utilities.scss已覆盖深层列表与嵌套任务列表的间距、项目符号和缩进无需额外写自定义 CSS。这份 Edge Case 文章不仅是主题自身的回归测试样本也是一份可直接对照的“列表语法速查表”当你在博客写作中遇到列表嵌套显示异常时回到这份文档比对缩进结构通常就能定位问题所在。【免费下载链接】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），仅供参考