Minimal Mistakes 页面创建指南：从 Sample Page 模板到自定义 About 与内容页

Minimal Mistakes 页面创建指南：从 Sample Page 模板到自定义 About 与内容页

【免费下载链接】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 主题附带的docs/_pages/sample-page.md示例页面为切入点，系统讲解在 Jekyll + Minimal Mistakes 主题中创建、组织与管理静态页面的完整方法。读完本文，你将掌握页面（Pages）与博客文章（Posts）的本质区别、_pages目录的组织规范、permalink 与 Front Matter 的配置技巧，以及如何基于主题的single布局快速搭建 About、联系、归档等各类自定义页面，并了解底层布局源码的工作原理。

什么是 Jekyll 页面，它与博客文章有何不同

sample-page.md的 Front Matter 非常简洁，只有四个字段：

--- title: "Sample Page" permalink: /sample-page/ date: 2016-02-24T03:02:20+00:00 ---

正如该示例页面所描述的：页面（Page）是"留在固定位置"的内容——它不随日期滚动、不进入按时间排序的文章流，而是长期稳定地出现在站点导航中（在大多数主题里都会展示在导航栏）。而博客文章（Post）则按发布时间归档、分页展示，并通常配有日期、阅读时间、相关文章等元信息。

两者的典型区分场景：

• 页面：About（关于我）、Contact（联系）、Terms（条款）、Portfolio（作品集入口）、归档页等长期稳定的内容；
• 文章：带有发布日期的博客日志、教程、新闻等随时间累积的内容。

在 Minimal Mistakes 的默认配置中（见 docs/_config.yml 的defaults段），文章（type: posts）默认启用layout: single、author_profile、read_time、comments、share、related等特性；而页面（type: pages）默认只启用layout: single和author_profile: true，刻意保持精简——这正是"页面内容需要长期稳定、不被时间轴打扰"的设计意图。

页面里通常写什么：参考 Sample Page 的两种典型内容

sample-page.md给出了两种最常见的页面内容范式，可以直接套用到你的 About 页面：

个人介绍型（个人博客 / 作品集）：

Hi there! I'm a bike messenger by day, aspiring actor by night, and this is my website. I live in Los Angeles, have a great dog named Jack, and I like pi'a coladas. (And gettin' caught in the rain.)

机构 / 产品介绍型（公司官网 / 项目主页）：

The XYZ Doohickey Company was founded in 1971, and has been providing quality doohickeys to the public ever since. Located in Gotham City, XYZ employs over 2,000 people and does all kinds of awesome things for the Gotham community.

仓库中docs/_pages/目录下的真实页面就是这些范式的实际应用：about.md（个人介绍）、terms.md（条款）、sitemap.md（站点地图）、sample-page.md（示例页）等。你可以直接复制这些文件到自己的站点作为起点，修改内容后使用。

组织页面：使用_pages目录统一管理

Minimal Mistakes 官方建议（见 Working with Pages 文档）把所有页面集中放到一个_pages目录中，便于管理。推荐的文件命名方式是语义化命名，避免像/about/index.md这样容易在多个index.md之间产生混淆的模式：

sample-project └── _pages/ ├── 404.md # custom 404 page ├── about.md # about page └── contact.md # contact page

创建_pages目录后，需要做两件事让 Jekyll 真正"看到"并处理这些文件：

Step 1：在_config.yml中加入include: ["_pages"]

include: - _pages

这是 Jekyll 处理下划线开头目录（默认会被排除）的关键步骤。仓库的 docs/_config.yml 正是这样配置的。

Step 2：在每个页面的 YAML Front Matter 中设置 permalink

filename	permalink
_pages/about.md	permalink: /about/
_pages/home.md	permalink: /
_pages/contact.md	permalink: /contact/

仓库中的实际例子可参考 docs/_pages/about.md 与 docs/_pages/404.md。sample-page.md本身也使用了permalink: /sample-page/来固定其访问地址。

通过 Front Matter Defaults 批量设置页面参数

逐页手写layout等重复配置效率很低。Jekyll 的 Front Matter Defaults 机制可以在_config.yml中按 scope 批量注入。文档推荐的页面默认配置如下：

defaults: # _pages - scope: path: "" type: pages values: layout: single author_profile: true

仓库实际使用的配置略有差异（docs/_config.yml 中scope.path为"_pages"），效果相同：所有页面自动应用single布局并显示作者侧边栏。任何页面仍可在自己的 Front Matter 中覆盖这些默认值，例如某页想隐藏作者侧边栏，写入author_profile: false即可。

页面使用什么布局：深入single布局源码

页面默认继承的single布局（源码见 _layouts/single.html）是 Minimal Mistakes 中最常用的布局，由default布局扩展而来，提供"侧边栏 + 主内容"双栏结构。从源码可以梳理出它对页面内容的核心处理流程：

1. Hero 区域：当 Front Matter 中设置了header.overlay_color、header.overlay_image或header.image时，渲染页面头图（page__hero.html）；
2. 面包屑：当site.breadcrumbs为true且当前页面不是首页时，渲染面包屑导航（breadcrumbs.html）；
3. 标题与元信息：默认（无 overlay 头图时）渲染页面标题和page__meta.html（日期、阅读时间、分类/标签等元信息）；
4. 目录（TOC）：当page.toc为true时，在右侧渲染自动生成的目录（基于toc.html，支持toc_label、toc_icon、toc_sticky参数）；
5. 内容区：输出{{ content }}，若设置了page.link则在末尾追加一个"Direct Link"按钮；
6. 页脚区：渲染分类/标签信息（page__taxonomy.html）与页面日期（page__date.html）；
7. 可选模块：page.share为true时渲染社交分享按钮；页面存在 ID 且related: true时渲染相关文章。

页面常用 Front Matter 参数速查表（均为可选，默认值见括号内）：

参数	作用	默认值
layout	使用的布局，页面通常为single	由 defaults 决定
permalink	覆盖页面访问地址	按文件名生成
title	页面标题	无
excerpt	页面摘要，用于 SEO meta description 与归档列表	自动取首段
author_profile	是否显示作者侧边栏	true（pages scope）
toc/toc_label/toc_icon/toc_sticky	控制右侧目录	false
classes: wide	扩展主内容宽度（占满原本目录的位置）	无
share	是否显示社交分享按钮	由 defaults 决定
comments	是否显示评论（需先在_config.yml配置评论提供方）	由 defaults 决定
search: false	从站点搜索索引中排除该页面	默认参与索引
header.image/header.overlay_image等	页面头图	无
canonical_url	自定义 canonical URL	自动生成

让页面更醒目：头图与全宽版式

给页面添加视觉头图只需在 Front Matter 中配置（图片建议放在assets/images/目录，宽度约1280px）：

header: image: /assets/images/unsplash-image-1.jpg image_description: "A description of the image" # 无障碍 alt 文本 caption: "Photo credit: Some photographer" # 图片说明，支持 Markdown

希望主内容区扩展、占满右侧原本留给目录的空间，可添加：

classes: wide

把页面接入站点导航

页面创建后要能被访问者找到，最简单的做法是加入主导航。Minimal Mistakes 的主导航由数据文件_data/navigation.yml的main键驱动（参考 docs/_data/navigation.yml）：

main: - title: "Quick-Start Guide" url: /docs/quick-start-guide/ - title: "Posts" url: /year-archive/ - title: "Pages" url: /page-archive/

导航采用 "priority plus" 设计模式：优先展示能放得下的链接，多余的折叠进菜单切换按钮。想添加自定义页面链接，只需追加一个title+url条目；可选地加description键，桌面端悬停时会显示提示文字；外部链接可加target: _blank新窗口打开。

对于文档型站点，还可以用_data/navigation.yml中的其他键（如docs）配合页面 Front Matter 的sidebar.nav: "docs"构建侧边栏导航菜单，支持一层嵌套子菜单——这与本仓库文档区（docs/_docs/各篇）的呈现方式一致。

从 Sample Page 出发的落地步骤

综合以上内容，把sample-page.md改造成你自己的 About 页面的完整流程是：

1. 复制docs/_pages/sample-page.md为_pages/about.md（或直接修改）；
2. 改写 Front Matter：设置有意义的title（如"About Me"）和permalink: /about/；
3. 删除示例占位内容，写入你的个人/团队介绍（可参考上文两种范式）；
4. 确认_config.yml中include: ["_pages"]与页面 defaults 已配置；
5. 可选：添加header.image头图、classes: wide全宽版式、share: true分享按钮；
6. 在_data/navigation.yml的main键中加入该页面链接；
7. 本地运行bundle exec jekyll serve预览，确认无问题后构建部署。

正如sample-page.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