Minimal Mistakes 作品集案例页编写指南：以 Baz Boom Identity 为例掌握 Collection 文档与画廊（Gallery）配置

Minimal Mistakes 作品集案例页编写指南：以 Baz Boom Identity 为例掌握 Collection 文档与画廊（Gallery）配置

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

本篇技术指南以仓库示例文档 docs/_portfolio/baz-boom-identity.md 为核心骨架，系统讲解在 Minimal Mistakes Jekyll 主题中如何为作品集（Portfolio）Collection 编写案例文档——从 Front Matter 元数据、header 头图、侧边栏（sidebar）角色信息卡，到画廊（gallery）的完整配置与galleryinclude 的渲染机制，并延伸说明归档页的 grid 展示与底层实现，帮助你直接照抄出可运行的案例页。

一、文档定位：一份"案例研究"型作品集条目

在 Minimal Mistakes 的官方文档站点中，baz-boom-identity.md属于_portfolioCollection 的四个示例条目之一（同目录还包含fizz-bang-identity.md、foo-bar-website.md、ginger-gulp-identity.md，另可参见 docs/_portfolio/foo-bar-website.md 对比）。它的定位是一份"品牌设计案例研究"（Baz Boom design system），涵盖 logo 设计、网站设计与品牌应用，是典型的个人作品集条目写法。

这份文档包含三层信息结构：

1. Front Matter 元数据：页面标题、摘要（excerpt）、header 头图、侧边栏信息、画廊图集；
2. 正文内容：一段项目背景叙述（该仓库示例使用占位文本，实际写作时应替换为自己的项目介绍）；
3. 画廊调用：通过{% include gallery %}将 Front Matter 中定义的图集渲染为可点击的图片网格。

从仓库结构看，_portfolio是被 docs/_config.yml 明确声明的 Collection：

collections: portfolio: output: true permalink: /:collection/:path/

output: true表示每个条目都会生成独立页面，permalink: /:collection/:path/则决定 URL 形态，例如baz-boom-identity.md会输出为/portfolio/baz-boom-identity/。同时，docs/_config.yml 中为portfolio类型配置了默认 Front Matter：

defaults: - scope: path: "" type: portfolio values: layout: single author_profile: false share: true

也就是说，即使条目 Front Matter 不写layout，也会自动套用single布局、隐藏作者侧边栏并开启分享按钮。

二、Front Matter 字段逐项拆解

baz-boom-identity.md的完整 Front Matter 如下：

--- title: "Baz Boom Identity" excerpt: "Baz Boom design system including logo mark, website design, and branding applications." header: image: /assets/images/unsplash-gallery-image-1.jpg teaser: assets/images/unsplash-gallery-image-1-th.jpg sidebar: - title: "Role" image: http://placehold.it/350x250 image_alt: "logo" text: "Designer, Front-End Developer" - title: "Responsibilities" text: "Reuters try PR stupid commenters should isn't a business model" gallery: - url: /assets/images/unsplash-gallery-image-1.jpg image_path: assets/images/unsplash-gallery-image-1-th.jpg alt: "placeholder image 1" - url: /assets/images/unsplash-gallery-image-2.jpg image_path: assets/images/unsplash-gallery-image-2-th.jpg alt: "placeholder image 2" - url: /assets/images/unsplash-gallery-image-3.jpg image_path: assets/images/unsplash-gallery-image-3-th.jpg alt: "placeholder image 3" ---

1.title与excerpt

• title：页面与归档条目显示的主标题；
• excerpt：案例的一句话摘要。在归档列表页中，它会被archive-single渲染为条目摘要。查看 _includes/archive-single.html 的源码可见其处理逻辑：

{% if post.excerpt %}<p class="archive__item-excerpt p-summary" itemprop="description">{{ post.excerpt | markdownify | strip_html | truncate: 160 }}</p>{% endif %}

即摘要经过 Markdown 渲染、去除 HTML 后，超过 160 个字符会被截断。因此给每个作品集条目写一句 160 字符以内的精炼摘要，能在归档页获得最佳展示效果。

2.header：头图与缩略图

header: image: /assets/images/unsplash-gallery-image-1.jpg teaser: assets/images/unsplash-gallery-image-1-th.jpg

• header.image：页面顶部的全宽头图（以/开头的站点根相对路径）；
• header.teaser：归档列表（尤其是 grid 布局）中使用的缩略图。

teaser的取值优先级体现在 _includes/archive-single.html：

{% if post.header.teaser %} {% capture teaser %}{{ post.header.teaser }}{% endcapture %} {% elsif post.header.image %} {% assign teaser = post.header.image %} {% else %} {% assign teaser = site.teaser %} {% endif %}

即：条目自身teaser优先 → 退而取header.image→ 再退而取站点级site.teaser。所以即使不写teaser，归档页也能从header.image回退获取缩略图。仓库中对应的图片资源位于 docs/assets/images/unsplash-gallery-image-1-th.jpg、docs/assets/images/unsplash-gallery-image-1.jpg 等文件。

3.sidebar：侧边栏信息卡

sidebar: - title: "Role" image: http://placehold.it/350x250 image_alt: "logo" text: "Designer, Front-End Developer" - title: "Responsibilities" text: "Reuters try PR stupid commenters should isn't a business model"

sidebar接受一个数组，每个元素是一张信息卡，支持title、image、image_alt、text四个字段。在single布局中，这组卡片会显示在页面侧边栏，用于呈现"角色""职责"等项目信息。实际使用时，应把image换成自己的作品图、把text换成真实的职责描述，并将示例占位文本替换掉。

4.gallery：画廊图集

gallery: - url: /assets/images/unsplash-gallery-image-1.jpg image_path: assets/images/unsplash-gallery-image-1-th.jpg alt: "placeholder image 1" - url: /assets/images/unsplash-gallery-image-2.jpg image_path: assets/images/unsplash-gallery-image-2-th.jpg alt: "placeholder image 2" - url: /assets/images/unsplash-gallery-image-3.jpg image_path: assets/images/unsplash-gallery-image-3-th.jpg alt: "placeholder image 3"

每个图集项包含三个字段：

• url：点击缩略图后跳转的大图地址；
• image_path：在页面上显示的缩略图路径；
• alt：图片替代文本，兼顾可访问性与 SEO。

三、画廊渲染原理：galleryinclude 源码解读

正文中通过一行 Liquid 调用画廊：

{% include gallery caption="This is a sample gallery to go along with this case study." %}

其渲染逻辑位于 _includes/gallery（无扩展名的 Liquid 模板）。核心源码如下：

{% if include.id %} {% assign gallery = page[include.id] %} {% else %} {% assign gallery = page.gallery %} {% endif %} {% if include.layout %} {% assign gallery_layout = include.layout %} {% else %} {% if gallery.size == 2 %} {% assign gallery_layout = 'half' %} {% elsif gallery.size >= 3 %} {% assign gallery_layout = 'third' %} {% else %} {% assign gallery_layout = '' %} {% endif %} {% endif %} <figure class="{{ gallery_layout }} {{ include.class }}"> {% for img in gallery %} {% if img.url %} <a href="{{ img.url | relative_url }}" {% if img.title %}title="{{ img.title | escape_once }}"{% endif %}> <img src="{{ img.image_path | relative_url }}" alt="{% if img.alt %}{{ img.alt | escape_once }}{% endif %}"> </a> {% else %} <img src="{{ img.image_path | relative_url }}" alt="{% if img.alt %}{{ img.alt | escape_once }}{% endif %}"> {% endif %} {% endfor %} {% if include.caption %} <figcaption>{{ include.caption | markdownify | remove: "<p>" | remove: "</p>" }}</figcaption> {% endif %} </figure>

由此可以总结出画廊 include 的完整使用规则：

1. 图集来源（id参数）

• 不带id时，默认渲染page.gallery；
• 带id时（如{% include gallery id="gallery2" %}），渲染page.gallery2，这允许一个页面配置多套图集，用不同 id 分别调用。

2. 布局（layout参数与自动推断）

• 显式传layout（如layout="half"）时优先使用；
• 否则自动推断：图集 2 张用half（半幅）、3 张及以上用third（三列）、少于 2 张则不附加布局类；
• class参数可追加自定义 CSS 类。

3. 渲染细节

• 每个图集项若有url，缩略图被包裹为超链接，并支持可选的title属性（经escape_once转义）；
• 图片src与链接href均经relative_url过滤器处理，兼容站点部署在子路径下的场景；
• alt同样经escape_once转义；
• caption支持 Markdown，输出前会剥离包裹的<p>标签。

baz-boom-identity 示例配置了 3 张图，因此自动采用third三列布局，缩略图各自链接到大图，页面上展示为一行三列的图集。

四、作品集归档页：从条目到 grid 列表

baz-boom-identity.md这类条目最终由归档页汇总展示。仓库中的归档页是 docs/_pages/portfolio-archive.md：

--- title: Portfolio layout: collection permalink: /portfolio/ collection: portfolio entries_layout: grid classes: wide --- Sample document listing for the collection `_portfolio`.

关键字段：

• layout: collection：使用 Collection 归档布局；
• collection: portfolio：指定要罗列的 Collection；
• entries_layout: grid：以网格形式展示条目（对应baz-boом等条目的header.teaser缩略图网格）。

collection布局的底层实现在 _layouts/collection.html：

{% assign entries_layout = page.entries_layout | default: 'list' %} <div class="entries-{{ entries_layout }}"> {% include documents-collection.html locale=locale collection=page.collection sort_by=page.sort_by sort_order=page.sort_order type=entries_layout %} </div>

它通过documents-collectioninclude 按sort_by/sort_order排序后，把每个条目的标题、摘要与缩略图渲染为列表（list）或网格（grid）卡片。网格模式下的缩略图输出逻辑在 _includes/archive-single.html：

{% if include.type == "grid" and teaser %} <div class="archive__item-teaser"> <img src="{{ teaser | relative_url }}" alt=""> </div> {% endif %}

即 grid 模式才会显示teaser缩略图——这也是为什么作品集条目都推荐配置header.teaser的原因。

五、将示例改造为自己的作品集条目

将baz-boom-identity.md的写法迁移到自己的项目，核心步骤为：

1. 复制结构：新建_portfolio/your-project.md，保留title、excerpt、header、sidebar、gallery等 Front Matter 键；
2. 替换资源路径：把header.image、header.teaser、gallery各项的url/image_path换成自己仓库assets/images/下的真实图片（注意示例中的http://placehold.it/350x250为占位图地址，实际应替换为本地资源）；
3. 填写真实正文：将示例中的占位文本替换为自己的项目背景、设计过程与成果说明；
4. 按需调整画廊：少于 3 张图会自动切换布局，或通过{% include gallery id="xxx" layout="half" %}显式控制；
5. 确认归档可见性：确保_config.yml中已声明portfolioCollection（含output: true），并在归档页（layout: collection）中指定collection: portfolio。

完成以上改造后，your-project.md即可生成独立的案例详情页，并自动出现在/portfolio/归档网格中，与仓库自带的四个示例条目保持一致的展示效果。

六、小结：本示例文档揭示了什么

baz-boom-identity.md虽然是一份以占位文本构成的示例文档，但它完整示范了 Minimal Mistakes 作品集场景的三项核心能力：

• Collection 驱动的独立条目页：Front Matter 元数据 +single布局默认值（docs/_config.yml）自动组合成案例详情页；
• galleryinclude 的声明式图集：通过 YAML 数组声明图片、自动推断布局、支持多图集与自定义布局，源码见 _includes/gallery；
• 归档网格的缩略图链路：header.teaser→archive-singlegrid 分支 → 归档页网格，形成从条目到列表的完整闭环。

对于需要搭建个人作品集或项目案例展示站的开发者，直接对照本文第三节的字段说明与第五节的改造步骤，就能把这份示例快速落地为自己的真实作品集页面。

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