Minimal Mistakes 主题 Archive 布局实战：在归档页中正确使用 Markdown 标记、按钮与通知样式

Minimal Mistakes 主题 Archive 布局实战：在归档页中正确使用 Markdown 标记、按钮与通知样式

【免费下载链接】minimal-mistakes:triangular_ruler: Jekyll theme for building a personal site, blog, project documentation, or portfolio.项目地址: https://gitcode.com/gh_mirrors/mi/minimal-mistakes

本篇技术指南以仓库中test/_pages/archive-layout-with-content.md这一"归档布局 + 富内容"示例页为核心，讲解 Minimal Mistakes Jekyll 主题中archive布局的页面如何通过 YAML Front Matter 声明、如何在其正文中安全使用从标题、引用、表格、定义列表、嵌套列表到按钮、通知和各类 HTML 标签的完整 Markdown 标记，并结合_layouts/archive.html、_includes/archive-single.html、_sass/minimal-mistakes/_buttons.scss、_notices.scss等源码说明每个样式类的底层实现。读完本文，你将能独立搭建一个既有归档列表又能在正文中排版丰富内容的页面，并懂得如何让这些内容与主题的样式系统对齐。

什么是 Archive 布局页面

archive是 Minimal Mistakes 主题中最常用的归档布局之一。它本质上与single布局相似，但去掉了评论、相关文章、分享链接等模块，专门用于把一组文章（posts）或页面（pages）以列表或网格的形式集中展示。

test/_pages/archive-layout-with-content.md就是这样一个典型页面，其 Front Matter 只有三行：

--- title: "Archive Layout with Content" layout: archive permalink: /archive-layout-with-content/ ---

• title：页面标题，会由主题渲染为<h1 id="page-title" class="page__title">；
• layout: archive：声明使用归档布局；
• permalink：自定义页面的最终 URL，与文件名无关。

页面正文的第一句话 "A variety of common markup showing how the theme styles them" 说明它的真实用途：作为一份"样式示范页"，验证主题对各类 Markdown 标记的渲染效果。这也是理解主题样式体系的捷径——仓库中所有排版相关的样式表都集中在 _sass/minimal-mistakes/ 目录下。

Archive 布局的渲染机制（源码解读）

要理解该页面中正文内容与归档列表的关系，需要先看布局的模板实现 _layouts/archive.html：

{%- assign locale = page.locale | default: layout.locale | default: site.locale %} {% if page.header.overlay_color or page.header.overlay_image or page.header.image %} {% include page__hero.html locale=locale %} {% elsif page.header.video.id and page.header.video.provider %} {% include page__hero_video.html %} {% endif %} {% if page.url != "/" and site.breadcrumbs %} {% unless paginator %} {% include breadcrumbs.html locale=locale %} {% endunless %} {% endif %} <div id="main" role="main"> {% include sidebar.html locale=locale %} <div class="archive"> {% unless page.header.overlay_color or page.header.overlay_image %} <h1 id="page-title" class="page__title"{% if page.locale %} lang="{{ page.locale }}"{% endif %}>{{ page.title }}</h1> {% endunless %} {{ content }} </div> </div>

关键点：

• 如果页面 Front Matter 中配置了header.overlay_color、header.overlay_image或header.image，会先引入 page__hero.html 渲染页头，否则页面标题<h1>直接显示在.archive容器内；
• 整个正文（{{ content }}）被包裹在<div class="archive">中，而.archive的宽度与浮动行为由 _sass/minimal-mistakes/_archive.scss 控制——在大屏断点（$large/$x-large）下它向右浮动并为右侧预留侧边栏宽度；
• 示例页面本身没有在正文中追加for循环列出所有页面，但仓库的 docs 版本docs/_pages/archive-layout-with-content.md末尾额外追加了这样一段，用于把全站页面以归档条目形式列出来：

{% for post in site.pages %} {% include archive-single.html %} {% endfor %}

这正体现了archive布局"正文 + 归档列表"二合一的典型用法。每一条目由 _includes/archive-single.html 渲染：默认以list类型输出<article class="archive__item">，标题、日期等 meta 信息、以及经markdownify | strip_html | truncate: 160处理后的 excerpt（摘要截断为 160 字符）都会按样式渲染；若传入type=grid则切换为网格视图并显示header.teaser缩略图。

上面这张截图来自官方文档站点（路径见 docs/_docs/10-layouts.md 中的 Archive layout 小节），展示了archive布局默认列表视图的呈现效果。更多布局细节，包括网格视图与entries_layout: grid的用法，可参考该文档。

标题层级与正文排版

示例页面从# Header one一直到###### Header six展示了六个层级的标题。在归档页正文中使用这些标题时需注意两点：

1. 页面自身的标题（Front Matter 的title）由布局渲染为<h1 id="page-title">，因此正文中建议从##开始组织小节，避免出现两个h1；
2. 如果页面启用了toc: true（目录），docs/_docs/10-layouts.md 明确指出：目录生成要求标题层级必须连续，例如从#跳到###（跳过##）会导致目录生成异常。

引用块（Blockquote）与出处标注

示例页面给出了两种引用块用法：

• 单行引用：

> Stay hungry. Stay foolish.

• 带出处引用的多行引用：

> People think focus means saying yes to the thing you've got to focus on. ... > > <cite>Steve Jobs</cite> --- Apple Worldwide Developers' Conference, 1997 {: .small}

其中{: .small}是 Kramdown 的块级属性语法，把small工具类附加到整个引用块上，用于缩小字号。这类"Markdown 正文 + Kramdown 属性"的组合是 Minimal Mistakes 主题内容排版的通用手法，在 _sass/minimal-mistakes/_utilities.scss 中定义了大量可搭配使用的工具类，详见 docs/_docs/15-utility-classes.md。

表格：对齐、多行单元格与分隔行

示例页面包含两张表格。第一张是普通的左对齐表格，第三列内容较长时表格会自动撑开，配合主题默认的表格样式（_sass/minimal-mistakes/_tables.scss）显示斑马纹与边框。

第二张表格演示了 Kramdown 表格的进阶能力——列对齐控制：

| Header1 | Header2 | Header3 | |:--------|:-------:|--------:| | cell1 | cell2 | cell3 | | cell4 | cell5 | cell6 | |-----------------------------| | cell1 | cell2 | cell3 | | cell4 | cell5 | cell6 | |=============================| | Foot1 | Foot2 | Foot3 |

语法要点：

• 分隔行中的:位置决定列对齐：:---左对齐、:---:居中、---:右对齐；
• 使用---（短横线）分隔行可以把表格拆成多个"数据区"，用===（等号）分隔行则模拟出"表尾（footer）"区域，Kramdown 会分别渲染为<tbody>与<tfoot>结构，主题样式会据此区分呈现。

定义列表（Definition List）

Kramdown 原生支持定义列表，示例页面中的写法如下：

Startup : A startup company or startup is a company or temporary organization designed to search for a repeatable and scalable business model. #dowork : Coined by Rob Dyrdek and his personal body guard Christopher "Big Black" Boykins, "Do Work" works as a self motivator, to motivating your friends.

格式为"术语行"后跟一个以:开头的缩进行作为定义。由于主题基于 Kramdown 渲染 Markdown（这也是 GitHub Pages 的默认渲染器），定义列表可以放心使用，<dl>、<dt>、<dd>会被 _sass/minimal-mistakes/_base.scss 中的样式正常排版。

嵌套列表：无序与有序

示例页面分别给出了三层嵌套的无序列表与有序列表：

* List item one * List item one * List item one * List item two * List item two * List item two

1. List item one 1. List item one 1. List item one 2. List item two 2. List item two 2. List item two

嵌套时只需对子列表缩进即可（示例中使用 4 空格缩进）。主题样式会为不同层级使用不同的列表符号（disc、circle、square等），有序列表的编号层级同样会正确递进。

按钮（.btn）：让链接变成按钮

示例页面用一整节展示了 Minimal Mistakes 的按钮系统。核心思路是：任何链接（<a>）只要加上.btn类就会变成按钮，再叠加btn--xxx修饰类即可切换颜色与尺寸。

HTML 写法：

<a href="#" class="btn--success">Success Button</a>

Kramdown 写法（在原文档中，普通链接用{: .btn}这种行内属性附加类名）：

[Primary Button](#){: .btn} [Success Button](#){: .btn .btn--success} [Warning Button](#){: .btn .btn--warning} [Danger Button](#){: .btn .btn--danger} [Info Button](#){: .btn .btn--info} [Inverse Button](#){: .btn .btn--inverse} [Light Outline Button](#){: .btn .btn--light-outline}

七种颜色修饰类的对应关系如下（详见 docs/_docs/15-utility-classes.md 中的 Buttons 一节）：

四种尺寸修饰类：

[X-Large Button](#){: .btn .btn--x-large} [Large Button](#){: .btn .btn--large} [Default Button](#){: .btn} [Small Button](#){: .btn .btn--small}

从源码看，这些类的实现位于 _sass/minimal-mistakes/_buttons.scss：

• .btn基础类定义了display: inline-block、内边距、border-radius、加粗字体等基础样式，字号取$type-size-6；
• 颜色通过 Sass 的$buttoncolors:颜色映射表批量生成，映射中的键会拼成btn--{name}类，值则来自 _sass/minimal-mistakes/_variables.scss 中的颜色变量：$primary-color: #6f777d、$success-color: #3fa63f、$warning-color: #d67f05、$danger-color: #ee5f5b、$info-color: #3b9cba；
• 文字颜色由yiq-contrasted()混入自动计算（深色背景配白字、浅色背景配黑字），hover 时颜色会向黑色混合 20% 形成加深效果；
• btn--inverse额外加了 1px 边框，btn--light-outline则用白色 1px 描边；
• 尺寸类通过覆盖font-size实现：x-large用$type-size-4、large用$type-size-5、small用$type-size-7。

如果希望扩展自定义颜色按钮（例如品牌色），只需在$buttoncolors:映射中新增(reddit, $reddit-color)这样的条目，并同时在_variables.scss定义对应颜色变量，重新编译 CSS 即可获得.btn--reddit类——这正是 docs/_docs/10-layouts.md 中"自定义社交分享按钮"一节的实现路径。

通知（Notice）：给段落加高亮提示框

示例页面中，"Watch out!" 一段通过追加{: .notice}变成了高亮提示块：

**Watch out!** You can also add notices by appending `{: .notice}` to a paragraph. {: .notice}

这是 Kramdown 块级属性作用于段落的典型用法。通知系统的实现位于 _sass/minimal-mistakes/_notices.scss，它定义了一个notice($notice-color)混入，为提示块统一设置内边距、圆角、左侧阴影和背景色混合（背景色由mix($background-color, $notice-color, $notice-background-mix)计算）。除了默认的.notice，还内置了 5 种语义化变体（均可用 Kramdown 属性直接附加到段落）：

同时源码中为.markdown-alert及其变体（.markdown-alert-important、.markdown-alert-note等）提供了相同的样式，说明主题也兼容 GitHub Flavored Markdown 的 alert 语法。

对于更复杂的内容（多段文字、列表、标题），docs/_docs/15-utility-classes.md 推荐把.notice系列类加到<div>上并使用markdown="1"属性，例如：

<div class="notice--info"> <h4>Notice Headline:</h4> <ul> <li>Bullet point 1</li> <li>Bullet point 2</li> </ul> </div>

HTML 标签全家桶：原生标签的样式化输出

示例页面最后用一整节验证主题对各类原生 HTML 标签的样式覆盖，这些标签无需任何 CSS 类即可获得主题化外观，是"在 Markdown 正文中直接嵌入 HTML"的合法性证明。逐一说明其语义与主题处理方式：

其中<pre>片段特意放置了一段超长文本，用于检验主题对pre溢出内容的处理；<abbr>与*[CSS]:的组合则是 Kramdown 缩写定义语法的标准用法，在纯 Markdown 中即可实现"悬停显示释义"的效果。

小结：把示例页迁移到自己的站点

test/_pages/archive-layout-with-content.md本质上是一份"样式测试清单"，但它同样是一个可以直接复用的页面骨架。要把它移植到自己的 Minimal Mistakes 站点，只需三步：

1. 复制该文件到你的_pages/目录，按需修改title与permalink；
2. 保留layout: archive；如果希望正文下方自动列出所有页面或某个集合的文档，参照 docs 版本在正文末尾追加{% for post in site.pages %}{% include archive-single.html %}{% endfor %}（列表用）或传入type=grid切换网格视图；
3. 正文中的每一种标记（标题、引用、表格、定义列表、嵌套列表、按钮、通知、HTML 标签）都可直接套用本文介绍的写法与类名，样式由主题自带 Sass 自动生效，无需额外 CSS。

需要进一步了解archive布局与其他布局（single、home、collection、category、tag等）的差异与 Front Matter 参数，可阅读 docs/_docs/10-layouts.md；按钮、通知、文本对齐等工具类的完整清单见 docs/_docs/15-utility-classes.md。

【免费下载链接】minimal-mistakes:triangular_ruler: Jekyll theme for building a personal site, blog, project documentation, or portfolio.项目地址: https://gitcode.com/gh_mirrors/mi/minimal-mistakes