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 主题中如何为作品集PortfolioCollection 编写案例文档——从 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 设计、网站设计与品牌应用是典型的个人作品集条目写法。这份文档包含三层信息结构Front Matter 元数据页面标题、摘要excerpt、header 头图、侧边栏信息、画廊图集正文内容一段项目背景叙述该仓库示例使用占位文本实际写作时应替换为自己的项目介绍画廊调用通过{% include gallery %}将 Front Matter 中定义的图集渲染为可点击的图片网格。从仓库结构看_portfolio是被 docs/_config.yml 明确声明的 Collectioncollections: 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 Matterdefaults: - 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 isnt 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与excerpttitle页面与归档条目显示的主标题excerpt案例的一句话摘要。在归档列表页中它会被archive-single渲染为条目摘要。查看 _includes/archive-single.html 的源码可见其处理逻辑{% if post.excerpt %}p classarchive__item-excerpt p-summary itempropdescription{{ 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.jpgheader.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 isnt a business modelsidebar接受一个数组每个元素是一张信息卡支持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 captionThis 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 idgallery2 %}渲染page.gallery2这允许一个页面配置多套图集用不同 id 分别调用。2. 布局layout参数与自动推断显式传layout如layouthalf时优先使用否则自动推断图集 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指定要罗列的 Collectionentries_layout: grid以网格形式展示条目对应baz-boом等条目的header.teaser缩略图网格。collection布局的底层实现在 _layouts/collection.html{% assign entries_layout page.entries_layout | default: list %} div classentries-{{ entries_layout }} {% include documents-collection.html localelocale collectionpage.collection sort_bypage.sort_by sort_orderpage.sort_order typeentries_layout %} /div它通过documents-collectioninclude 按sort_by/sort_order排序后把每个条目的标题、摘要与缩略图渲染为列表list或网格grid卡片。网格模式下的缩略图输出逻辑在 _includes/archive-single.html{% if include.type grid and teaser %} div classarchive__item-teaser img src{{ teaser | relative_url }} alt /div {% endif %}即 grid 模式才会显示teaser缩略图——这也是为什么作品集条目都推荐配置header.teaser的原因。五、将示例改造为自己的作品集条目将baz-boom-identity.md的写法迁移到自己的项目核心步骤为复制结构新建_portfolio/your-project.md保留title、excerpt、header、sidebar、gallery等 Front Matter 键替换资源路径把header.image、header.teaser、gallery各项的url/image_path换成自己仓库assets/images/下的真实图片注意示例中的http://placehold.it/350x250为占位图地址实际应替换为本地资源填写真实正文将示例中的占位文本替换为自己的项目背景、设计过程与成果说明按需调整画廊少于 3 张图会自动切换布局或通过{% include gallery idxxx layouthalf %}显式控制确认归档可见性确保_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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考