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 idpage-title classpage__titlelayout: 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 localelocale %} {% 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 localelocale %} {% endunless %} {% endif %} div idmain rolemain {% include sidebar.html localelocale %} div classarchive {% unless page.header.overlay_color or page.header.overlay_image %} h1 idpage-title classpage__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 classarchive中而.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 classarchive__item标题、日期等 meta 信息、以及经markdownify | strip_html | truncate: 160处理后的 excerpt摘要截断为 160 字符都会按样式渲染若传入typegrid则切换为网格视图并显示header.teaser缩略图。上面这张截图来自官方文档站点路径见 docs/_docs/10-layouts.md 中的 Archive layout 小节展示了archive布局默认列表视图的呈现效果。更多布局细节包括网格视图与entries_layout: grid的用法可参考该文档。标题层级与正文排版示例页面从# Header one一直到###### Header six展示了六个层级的标题。在归档页正文中使用这些标题时需注意两点页面自身的标题Front Matter 的title由布局渲染为h1 idpage-title因此正文中建议从##开始组织小节避免出现两个h1如果页面启用了toc: true目录docs/_docs/10-layouts.md 明确指出目录生成要求标题层级必须连续例如从#跳到###跳过##会导致目录生成异常。引用块Blockquote与出处标注示例页面给出了两种引用块用法单行引用 Stay hungry. Stay foolish.带出处引用的多行引用 People think focus means saying yes to the thing youve got to focus on. ... citeSteve 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 ListKramdown 原生支持定义列表示例页面中的写法如下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 two1. 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# classbtn--successSuccess Button/aKramdown 写法在原文档中普通链接用{: .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 一节按钮类型类名默认主色.btn/.btn--primary成功.btn--success警告.btn--warning危险.btn--danger信息.btn--info反色白底.btn--inverse浅色描边.btn--light-outline四种尺寸修饰类[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 属性直接附加到段落通知类型类名对应颜色变量默认.notice$light-gray主要.notice--primary$primary-color信息.notice--info$info-color警告.notice--warning$warning-color成功.notice--success$success-color危险.notice--danger$danger-color同时源码中为.markdown-alert及其变体.markdown-alert-important、.markdown-alert-note等提供了相同的样式说明主题也兼容 GitHub Flavored Markdown 的 alert 语法。对于更复杂的内容多段文字、列表、标题docs/_docs/15-utility-classes.md 推荐把.notice系列类加到div上并使用markdown1属性例如div classnotice--info h4Notice Headline:/h4 ul liBullet point 1/li liBullet point 2/li /ul /divHTML 标签全家桶原生标签的样式化输出示例页面最后用一整节验证主题对各类原生 HTML 标签的样式覆盖这些标签无需任何 CSS 类即可获得主题化外观是在 Markdown 正文中直接嵌入 HTML的合法性证明。逐一说明其语义与主题处理方式标签语义示例内容主题样式说明address联系信息1 Infinite Loop, Cupertino斜体显示a超链接带title提示的链接使用$link-color由$info-color混合 20% 黑色得到并带下划线abbr*[CSS]: ...缩写词CSS stands for Cascading Style SheetsKramdown 会把*[CSS]:定义转换为abbr title...悬停显示全称cite出处引用Code is poetry. --- Automattic斜体渲染code行内代码word-wrap: break-word;等宽字体 浅灰背景strike删除线strikestrikeout text/strike删除线样式em强调斜体_italicize_斜体ins插入文本insinserted/ins下划线样式kbd键盘按键kbdkeyboard text/kbd模仿code样式的按键外观pre预格式化代码块长 CSS 片段保留空白与换行测试超长行溢出行为q行内短引用Developers, developers, developers…引号包裹strong加粗**bold text**加粗sub下标Hsub2/subO下标sup上标E MCsup2/sup上标var变量varvariables/var斜体变量样式其中pre片段特意放置了一段超长文本用于检验主题对pre溢出内容的处理abbr与*[CSS]:的组合则是 Kramdown 缩写定义语法的标准用法在纯 Markdown 中即可实现悬停显示释义的效果。小结把示例页迁移到自己的站点test/_pages/archive-layout-with-content.md本质上是一份样式测试清单但它同样是一个可以直接复用的页面骨架。要把它移植到自己的 Minimal Mistakes 站点只需三步复制该文件到你的_pages/目录按需修改title与permalink保留layout: archive如果希望正文下方自动列出所有页面或某个集合的文档参照 docs 版本在正文末尾追加{% for post in site.pages %}{% include archive-single.html %}{% endfor %}列表用或传入typegrid切换网格视图正文中的每一种标记标题、引用、表格、定义列表、嵌套列表、按钮、通知、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考