Minimal Mistakes 主题图片画廊Gallery完全指南从 YAML 配置到 Magnific Popup 灯箱【免费下载链接】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 Jekyll 主题内置的轻量级内容增强模块它让你无需编写任何 HTML仅凭 YAML Front Matter 中的一段数据声明与一行 Liquid include即可在文章、作品集portfolio或页面中渲染出基于figure语义结构的响应式图片墙并自动叠加灯箱预览、分组导航与标题说明。本文以主题示例文章 2010-09-09-post-gallery.md 为核心脉络结合 画廊 include 源码、Magnific Popup 初始化脚本 与官方 Helpers 文档 中的参数规范带你完整掌握画廊的定义、多画廊管理、外部图片托管、列布局覆盖与 caption 用法并深入底层源码理解每一处渲染细节。一、画廊的本质数据声明 单行 include在 Minimal Mistakes 中画廊并不是一个独立的 Layout而是一个数据驱动的 include 组件。它的工作流程分为两步在文章或页面的 YAML Front Matter 中用数组形式声明一组图片含缩略图、原图、alt 与标题在正文任意位置插入一行{% include gallery ... %}主题便会将这组图片渲染为标准的figure结构。官方文档对该组件的定位是Generate afigureelement with optional caption of arrays with two or more images即为两张及以上图片生成带可选说明文字的 figure 元素。从 示例文章 front matter 可以看到最基础的数据形态gallery: - url: /assets/images/unsplash-gallery-image-1.jpg image_path: /assets/images/unsplash-gallery-image-1-th.jpg alt: placeholder image 1 title: Image 1 title caption - url: /assets/images/unsplash-gallery-image-2.jpg image_path: /assets/images/unsplash-gallery-image-2-th.jpg alt: placeholder image 2 title: Image 2 title caption - url: /assets/images/unsplash-gallery-image-3.jpg image_path: /assets/images/unsplash-gallery-image-3-th.jpg alt: placeholder image 3 title: Image 3 title caption - url: /assets/images/unsplash-gallery-image-4.jpg image_path: /assets/images/unsplash-gallery-image-4-th.jpg alt: placeholder image 4 title: Image 4 title caption然后只要在正文中drop-in一行{% raw %}{% include gallery captionThis is a sample gallery with **Markdown support**. %}{% endraw %}主题会自动完成剩余工作。示例文章中 gallery 之后的段落也特意验证了画廊组件不会破坏后续正文的排版This is some text after the gallery just to make sure that everything aligns properly.说明画廊作为块级元素能够与前后文本正确对齐。二、画廊数据字段详解url / image_path / alt / title根据 14-helpers.md 中的参数表每个画廊条目支持四个字段字段必填说明url可选图片链接地址通常指向大图如高清原图或详情页image_path必填图片完整路径如/assets/images/filename.jpg外部托管的图片请使用绝对 URLalt可选图片的替代文本无障碍与 SEOtitle可选图片标题文字当配合url链接到大图时该标题会作为 Magnific Popup 灯箱叠加层中的图片说明显示这四个字段在 include 源码 中被精确消费{% 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 %}从源码可以确认几个重要实现细节url决定渲染形态条目含url时缩略图被包裹在a链接中便于点击放大或跳转不含url时只渲染裸img。示例文章中的gallery3正是无url的纯展示形态见下文第五节。路径过滤image_path与url都会经过relative_url过滤器因此在 YAML 中推荐写以/开头的站内绝对路径如/assets/images/xxx.jpg主题会自动拼接站点 baseurl。安全转义alt与title均经过escape_once处理避免引号或特殊字符破坏 HTML 属性。这一行为在 18-history.md 中有明确记录Addescape_onceto gallery title and alt text.。alt 兜底alt缺省时输出空字符串不会产生 undefined 之类的渲染错误。三、默认布局推导图片数量决定列数画廊最具实用性的特性之一是自适应列布局——不需要你手动指定列数主题会根据图片数量自动推导。核心逻辑位于 include 源码{% 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 %}对应 官方文档 的描述图片数量默认布局说明2 张half两列并排3 张及以上third三列并排其他如 1 张空单列全宽这一按数量自动选布局的设计来自社区的 PR 支持在 18-history.md 中记录为Add support to gallery helper for defining column layout (half,third, or single)。gallery_layout最终被写入figure的 class 属性figure class{{ gallery_layout }} {{ include.class }}再由主题的 SCSS 样式表完成网格布局渲染。四、include 参数全解析id / layout / class / caption示例文章 与 14-helpers.md 共同定义了 include 的四个可选参数include 参数必填说明默认值id可选当一篇文章包含多个画廊时通过该参数指定 YAML 中对应的画廊变量名gallerylayout可选列布局类型half两列、third三列、空单列按图片数量自动推导class可选为外层figure追加额外的 class便于自定义样式无caption可选画廊整体说明文字支持 Markdown 语法无4.1 caption支持 Markdown 的图注最简单的用法是不带id直接使用默认的gallery变量并添加说明{% raw %}{% include gallery captionThis is a sample gallery with **Markdown support**. %}{% endraw %}caption的处理逻辑在 include 源码{% if include.caption %} figcaption{{ include.caption | markdownify | remove: p | remove: /p }}/figcaption {% endif %}值得注意的是caption 会先经过markdownify过滤器将 Markdown 编译为 HTML所以**Markdown support**会渲染为加粗文字随后又用remove剥掉外层多余的p标签确保figcaption内部是干净的 HTML 片段。4.2 id一个文档管理多个画廊示例文章演示了如何在一篇文档中定义并渲染多个画廊。除默认gallery外还定义了gallery2外部托管图片与gallery3纯缩略图展示并通过id参数分别引用。id的取值逻辑位于 include 源码{% if include.id %} {% assign gallery page[include.id] %} {% else %} {% assign gallery page.gallery %} {% endif %}即id指定时从当前页面的 Front Matter 中按该变量名取数组未指定时回退到page.gallery。示例中的调用方式{% raw %}{% include gallery idgallery2 captionThis is a second gallery example with images hosted externally. %}{% endraw %}历史提醒早期版本曾因{{ page.[include.id] }}的写法存在 Liquid 语法解析问题已在 18-history.md 中记录修复当前实现使用page[include.id]方括号语法稳定可靠。4.3 classfull撑满内容容器示例文章的第三个画廊演示了class参数{% raw %}{% include gallery idgallery3 classfull captionThis is a third gallery example with two images and fills the entire content container. %}{% endraw %}class会被原样拼接到figure的 class 列表中figure classhalf fullfull类让画廊撑满整个页面内容容器常用于强调型视觉展示。4.4 layouthalf显式覆盖默认列布局最后示例文章展示了显式覆盖布局的能力{% raw %}{% include gallery idgallery layouthalf captionThis is a half gallery layout example. %}{% endraw %}当你不满足于按数量自动推导时可以用layout参数强制指定half、third或单列。比如 4 张图默认是third三列布局强制half即可改为两列。五、三种数据形态与外部图片托管示例文章的 Front Matter 中定义了三个画廊变量恰好覆盖了三种典型使用场景场景一gallery—— 站内图片 点击放大12 个条目全部使用站内路径/assets/images/unsplash-gallery-image-*.jpg为原图*-th.jpg为缩略图并同时提供url、alt、title是最完整的配置形态。场景二gallery2—— 外部托管图片gallery2: - url: https://flic.kr/p/8a6Ven image_path: https://farm2.staticflickr.com/1272/4697500467_8294dac099_q.jpg alt: Black and grays with a hint of green - url: https://flic.kr/p/8a738X image_path: https://farm5.staticflickr.com/4029/4697523701_249e93ba23_q.jpg alt: Made for open text placement - url: https://flic.kr/p/8a6VXP image_path: https://farm5.staticflickr.com/4046/4697502929_72c612c636_q.jpg alt: Fog in the trees这一场景证明画廊完全支持外部图片服务只要image_path与url填写完整的绝对 URL主题的relative_url过滤器会原样保留外部地址图片直接由外部 CDN 加载。适合图床、Flickr、Unsplash 等托管方案的接入。场景三gallery3—— 纯缩略图展示无链接gallery3: - image_path: /assets/images/unsplash-gallery-image-2-th.jpg alt: placeholder image 2 - image_path: /assets/images/unsplash-gallery-image-4-th.jpg alt: placeholder image 4该形态只保留image_path与alt不提供url——由源码可知这类条目将渲染为无链接的裸img适合不需要点击放大的装饰性图片墙。同时gallery3只有 2 张图会触发默认的half两列布局。六、底层联动Magnific Popup 灯箱是如何生效的画廊的点击缩略图 → 弹窗查看大图交互并非由 include 单独完成而是依赖主题集成的 Magnific Popup 插件与 assets/js/_main.js 中的初始化逻辑。_main.js首先为所有包含图片的链接打上灯箱标记$( a[href$.jpg],a[href$.jpeg],a[href$.JPG],a[href$.png],a[href$.gif],a[href$.webp] ).has( img).addClass(image-popup);画廊 include 生成的aimg/a结构恰好匹配a[href$.jpg]且包含子img的选择器因此带url的画廊条目会自动获得image-popup类并接入灯箱。随后对.image-popup执行 Magnific Popup 初始化$(.image-popup).magnificPopup({ type: image, gallery: { enabled: true, navigateByImgClick: true, preload: [0, 1], // 预加载当前图片的前后各一张 }, removalDelay: 500, mainClass: mfp-zoom-in, closeOnContentClick: true, midClick: true, });关键配置的含义gallery.enabled: true—— 启用画廊模式弹窗内可左右切换同一页面中的所有灯箱图片这正是文档中title字段会在 Magnific Popup 叠加层中作为说明显示的实现前提preload: [0, 1]—— 预加载当前图片之前 0 张、之后 1 张提升切换流畅度mainClass: mfp-zoom-in—— 配合 magnific-popup SCSS 中的动画类实现缩放过渡效果midClick: true—— 支持鼠标中键在新标签打开大图。这意味着画廊的灯箱体验是全站自动生效的——不只画廊 include正文中任何a包裹的图片链接都会获得同样的弹窗交互而画廊只是其中组织最规整的一种形态。七、路径规范与版本演进要点使用画廊前需要注意路径书写规范。根据 01-quick-start-guide.md 与 10-layouts.md 中的 v4 破坏性变更说明Paths for image headers, overlays, teasers, galleries, and feature rows have changed and now require a full path. Instead of justimage: filename.jpgyoull need to use the full path eg:image: /assets/images/filename.jpg. The preferred location is now/assets/images/.即v4 起必须使用完整路径如/assets/images/filename.jpg推荐统一存放在/assets/images/目录下该要求同样适用于_config.yml与author.yml中的图片引用。八、实战速查三步接入画廊综合以上内容为你的文章接入画廊只需三步第一步将图片放入assets/images/或使用外部 URL并在 Front Matter 声明数组gallery: - image_path: /assets/images/unsplash-gallery-image-1-th.jpg alt: Image 1 title: Image 1 title caption - image_path: /assets/images/unsplash-gallery-image-2-th.jpg alt: Image 2 title: Image 2 title caption第二步在正文需要的位置插入 include可叠加id/layout/class/caption{% raw %}{% include gallery caption我的作品集展示 %}{% endraw %}第三步本地预览验证。运行jekyll serve或bundle exec jekyll serve参考 Gemfile 与 Rakefile后访问页面检查图片是否按预期列数排列、点击后灯箱是否正常弹出、caption 中的 Markdown 是否生效。可复用资源示例文章引用的占位图unsplash-gallery-image-1.jpg至unsplash-gallery-image-4.jpg及对应*-th.jpg缩略图均位于 docs/assets/images可直接复制用于本地测试test/_posts/2010-09-09-post-gallery.md与test/_portfolio/下的四个作品集页面如 foo-bar-website.md也提供了画廊在真实项目中的落地样例。九、画廊 vs 其他图片组织方式在 Minimal Mistakes 中图片展示还有另外几种形态理解差异有助于选对工具Gallery include多图数组、自动网格、灯箱联动适合相册、作品集、截图对比本文主题Feature row面向splash页面布局的特性块排版每个块可含图与文字适合首页卖点展示见 14-helpers.md图片标题/头部/Teaser通过 Front Matter 的header、teaser等字段设置文章封面与正文画廊无直接关系。十、小结Minimal Mistakes 的画廊组件是一套配置即所得的图片组织方案在 YAML Front Matter 声明数据用一行 gallery include 渲染结构再由 Magnific Popup 初始化代码 提供灯箱交互。它同时支持站内图片与外部图床、多画廊管理id、自动/手动列布局layout、Markdown 图注caption与自定义样式扩展class。掌握这套机制后你便可以在文章、页面或 portfolio 集合中快速搭建专业级的图片展示区块而无需触碰任何原生 HTML 与 JavaScript。【免费下载链接】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），仅供参考 Minimal Mistakes 主题图片画廊（Gallery）完全指南：从 YAML 配置到 Magnific Popup 灯箱
Minimal Mistakes 主题图片画廊Gallery完全指南从 YAML 配置到 Magnific Popup 灯箱【免费下载链接】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 Jekyll 主题内置的轻量级内容增强模块它让你无需编写任何 HTML仅凭 YAML Front Matter 中的一段数据声明与一行 Liquid include即可在文章、作品集portfolio或页面中渲染出基于figure语义结构的响应式图片墙并自动叠加灯箱预览、分组导航与标题说明。本文以主题示例文章 2010-09-09-post-gallery.md 为核心脉络结合 画廊 include 源码、Magnific Popup 初始化脚本 与官方 Helpers 文档 中的参数规范带你完整掌握画廊的定义、多画廊管理、外部图片托管、列布局覆盖与 caption 用法并深入底层源码理解每一处渲染细节。一、画廊的本质数据声明 单行 include在 Minimal Mistakes 中画廊并不是一个独立的 Layout而是一个数据驱动的 include 组件。它的工作流程分为两步在文章或页面的 YAML Front Matter 中用数组形式声明一组图片含缩略图、原图、alt 与标题在正文任意位置插入一行{% include gallery ... %}主题便会将这组图片渲染为标准的figure结构。官方文档对该组件的定位是Generate afigureelement with optional caption of arrays with two or more images即为两张及以上图片生成带可选说明文字的 figure 元素。从 示例文章 front matter 可以看到最基础的数据形态gallery: - url: /assets/images/unsplash-gallery-image-1.jpg image_path: /assets/images/unsplash-gallery-image-1-th.jpg alt: placeholder image 1 title: Image 1 title caption - url: /assets/images/unsplash-gallery-image-2.jpg image_path: /assets/images/unsplash-gallery-image-2-th.jpg alt: placeholder image 2 title: Image 2 title caption - url: /assets/images/unsplash-gallery-image-3.jpg image_path: /assets/images/unsplash-gallery-image-3-th.jpg alt: placeholder image 3 title: Image 3 title caption - url: /assets/images/unsplash-gallery-image-4.jpg image_path: /assets/images/unsplash-gallery-image-4-th.jpg alt: placeholder image 4 title: Image 4 title caption然后只要在正文中drop-in一行{% raw %}{% include gallery captionThis is a sample gallery with **Markdown support**. %}{% endraw %}主题会自动完成剩余工作。示例文章中 gallery 之后的段落也特意验证了画廊组件不会破坏后续正文的排版This is some text after the gallery just to make sure that everything aligns properly.说明画廊作为块级元素能够与前后文本正确对齐。二、画廊数据字段详解url / image_path / alt / title根据 14-helpers.md 中的参数表每个画廊条目支持四个字段字段必填说明url可选图片链接地址通常指向大图如高清原图或详情页image_path必填图片完整路径如/assets/images/filename.jpg外部托管的图片请使用绝对 URLalt可选图片的替代文本无障碍与 SEOtitle可选图片标题文字当配合url链接到大图时该标题会作为 Magnific Popup 灯箱叠加层中的图片说明显示这四个字段在 include 源码 中被精确消费{% 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 %}从源码可以确认几个重要实现细节url决定渲染形态条目含url时缩略图被包裹在a链接中便于点击放大或跳转不含url时只渲染裸img。示例文章中的gallery3正是无url的纯展示形态见下文第五节。路径过滤image_path与url都会经过relative_url过滤器因此在 YAML 中推荐写以/开头的站内绝对路径如/assets/images/xxx.jpg主题会自动拼接站点 baseurl。安全转义alt与title均经过escape_once处理避免引号或特殊字符破坏 HTML 属性。这一行为在 18-history.md 中有明确记录Addescape_onceto gallery title and alt text.。alt 兜底alt缺省时输出空字符串不会产生 undefined 之类的渲染错误。三、默认布局推导图片数量决定列数画廊最具实用性的特性之一是自适应列布局——不需要你手动指定列数主题会根据图片数量自动推导。核心逻辑位于 include 源码{% 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 %}对应 官方文档 的描述图片数量默认布局说明2 张half两列并排3 张及以上third三列并排其他如 1 张空单列全宽这一按数量自动选布局的设计来自社区的 PR 支持在 18-history.md 中记录为Add support to gallery helper for defining column layout (half,third, or single)。gallery_layout最终被写入figure的 class 属性figure class{{ gallery_layout }} {{ include.class }}再由主题的 SCSS 样式表完成网格布局渲染。四、include 参数全解析id / layout / class / caption示例文章 与 14-helpers.md 共同定义了 include 的四个可选参数include 参数必填说明默认值id可选当一篇文章包含多个画廊时通过该参数指定 YAML 中对应的画廊变量名gallerylayout可选列布局类型half两列、third三列、空单列按图片数量自动推导class可选为外层figure追加额外的 class便于自定义样式无caption可选画廊整体说明文字支持 Markdown 语法无4.1 caption支持 Markdown 的图注最简单的用法是不带id直接使用默认的gallery变量并添加说明{% raw %}{% include gallery captionThis is a sample gallery with **Markdown support**. %}{% endraw %}caption的处理逻辑在 include 源码{% if include.caption %} figcaption{{ include.caption | markdownify | remove: p | remove: /p }}/figcaption {% endif %}值得注意的是caption 会先经过markdownify过滤器将 Markdown 编译为 HTML所以**Markdown support**会渲染为加粗文字随后又用remove剥掉外层多余的p标签确保figcaption内部是干净的 HTML 片段。4.2 id一个文档管理多个画廊示例文章演示了如何在一篇文档中定义并渲染多个画廊。除默认gallery外还定义了gallery2外部托管图片与gallery3纯缩略图展示并通过id参数分别引用。id的取值逻辑位于 include 源码{% if include.id %} {% assign gallery page[include.id] %} {% else %} {% assign gallery page.gallery %} {% endif %}即id指定时从当前页面的 Front Matter 中按该变量名取数组未指定时回退到page.gallery。示例中的调用方式{% raw %}{% include gallery idgallery2 captionThis is a second gallery example with images hosted externally. %}{% endraw %}历史提醒早期版本曾因{{ page.[include.id] }}的写法存在 Liquid 语法解析问题已在 18-history.md 中记录修复当前实现使用page[include.id]方括号语法稳定可靠。4.3 classfull撑满内容容器示例文章的第三个画廊演示了class参数{% raw %}{% include gallery idgallery3 classfull captionThis is a third gallery example with two images and fills the entire content container. %}{% endraw %}class会被原样拼接到figure的 class 列表中figure classhalf fullfull类让画廊撑满整个页面内容容器常用于强调型视觉展示。4.4 layouthalf显式覆盖默认列布局最后示例文章展示了显式覆盖布局的能力{% raw %}{% include gallery idgallery layouthalf captionThis is a half gallery layout example. %}{% endraw %}当你不满足于按数量自动推导时可以用layout参数强制指定half、third或单列。比如 4 张图默认是third三列布局强制half即可改为两列。五、三种数据形态与外部图片托管示例文章的 Front Matter 中定义了三个画廊变量恰好覆盖了三种典型使用场景场景一gallery—— 站内图片 点击放大12 个条目全部使用站内路径/assets/images/unsplash-gallery-image-*.jpg为原图*-th.jpg为缩略图并同时提供url、alt、title是最完整的配置形态。场景二gallery2—— 外部托管图片gallery2: - url: https://flic.kr/p/8a6Ven image_path: https://farm2.staticflickr.com/1272/4697500467_8294dac099_q.jpg alt: Black and grays with a hint of green - url: https://flic.kr/p/8a738X image_path: https://farm5.staticflickr.com/4029/4697523701_249e93ba23_q.jpg alt: Made for open text placement - url: https://flic.kr/p/8a6VXP image_path: https://farm5.staticflickr.com/4046/4697502929_72c612c636_q.jpg alt: Fog in the trees这一场景证明画廊完全支持外部图片服务只要image_path与url填写完整的绝对 URL主题的relative_url过滤器会原样保留外部地址图片直接由外部 CDN 加载。适合图床、Flickr、Unsplash 等托管方案的接入。场景三gallery3—— 纯缩略图展示无链接gallery3: - image_path: /assets/images/unsplash-gallery-image-2-th.jpg alt: placeholder image 2 - image_path: /assets/images/unsplash-gallery-image-4-th.jpg alt: placeholder image 4该形态只保留image_path与alt不提供url——由源码可知这类条目将渲染为无链接的裸img适合不需要点击放大的装饰性图片墙。同时gallery3只有 2 张图会触发默认的half两列布局。六、底层联动Magnific Popup 灯箱是如何生效的画廊的点击缩略图 → 弹窗查看大图交互并非由 include 单独完成而是依赖主题集成的 Magnific Popup 插件与 assets/js/_main.js 中的初始化逻辑。_main.js首先为所有包含图片的链接打上灯箱标记$( a[href$.jpg],a[href$.jpeg],a[href$.JPG],a[href$.png],a[href$.gif],a[href$.webp] ).has( img).addClass(image-popup);画廊 include 生成的aimg/a结构恰好匹配a[href$.jpg]且包含子img的选择器因此带url的画廊条目会自动获得image-popup类并接入灯箱。随后对.image-popup执行 Magnific Popup 初始化$(.image-popup).magnificPopup({ type: image, gallery: { enabled: true, navigateByImgClick: true, preload: [0, 1], // 预加载当前图片的前后各一张 }, removalDelay: 500, mainClass: mfp-zoom-in, closeOnContentClick: true, midClick: true, });关键配置的含义gallery.enabled: true—— 启用画廊模式弹窗内可左右切换同一页面中的所有灯箱图片这正是文档中title字段会在 Magnific Popup 叠加层中作为说明显示的实现前提preload: [0, 1]—— 预加载当前图片之前 0 张、之后 1 张提升切换流畅度mainClass: mfp-zoom-in—— 配合 magnific-popup SCSS 中的动画类实现缩放过渡效果midClick: true—— 支持鼠标中键在新标签打开大图。这意味着画廊的灯箱体验是全站自动生效的——不只画廊 include正文中任何a包裹的图片链接都会获得同样的弹窗交互而画廊只是其中组织最规整的一种形态。七、路径规范与版本演进要点使用画廊前需要注意路径书写规范。根据 01-quick-start-guide.md 与 10-layouts.md 中的 v4 破坏性变更说明Paths for image headers, overlays, teasers, galleries, and feature rows have changed and now require a full path. Instead of justimage: filename.jpgyoull need to use the full path eg:image: /assets/images/filename.jpg. The preferred location is now/assets/images/.即v4 起必须使用完整路径如/assets/images/filename.jpg推荐统一存放在/assets/images/目录下该要求同样适用于_config.yml与author.yml中的图片引用。八、实战速查三步接入画廊综合以上内容为你的文章接入画廊只需三步第一步将图片放入assets/images/或使用外部 URL并在 Front Matter 声明数组gallery: - image_path: /assets/images/unsplash-gallery-image-1-th.jpg alt: Image 1 title: Image 1 title caption - image_path: /assets/images/unsplash-gallery-image-2-th.jpg alt: Image 2 title: Image 2 title caption第二步在正文需要的位置插入 include可叠加id/layout/class/caption{% raw %}{% include gallery caption我的作品集展示 %}{% endraw %}第三步本地预览验证。运行jekyll serve或bundle exec jekyll serve参考 Gemfile 与 Rakefile后访问页面检查图片是否按预期列数排列、点击后灯箱是否正常弹出、caption 中的 Markdown 是否生效。可复用资源示例文章引用的占位图unsplash-gallery-image-1.jpg至unsplash-gallery-image-4.jpg及对应*-th.jpg缩略图均位于 docs/assets/images可直接复制用于本地测试test/_posts/2010-09-09-post-gallery.md与test/_portfolio/下的四个作品集页面如 foo-bar-website.md也提供了画廊在真实项目中的落地样例。九、画廊 vs 其他图片组织方式在 Minimal Mistakes 中图片展示还有另外几种形态理解差异有助于选对工具Gallery include多图数组、自动网格、灯箱联动适合相册、作品集、截图对比本文主题Feature row面向splash页面布局的特性块排版每个块可含图与文字适合首页卖点展示见 14-helpers.md图片标题/头部/Teaser通过 Front Matter 的header、teaser等字段设置文章封面与正文画廊无直接关系。十、小结Minimal Mistakes 的画廊组件是一套配置即所得的图片组织方案在 YAML Front Matter 声明数据用一行 gallery include 渲染结构再由 Magnific Popup 初始化代码 提供灯箱交互。它同时支持站内图片与外部图床、多画廊管理id、自动/手动列布局layout、Markdown 图注caption与自定义样式扩展class。掌握这套机制后你便可以在文章、页面或 portfolio 集合中快速搭建专业级的图片展示区块而无需触碰任何原生 HTML 与 JavaScript。【免费下载链接】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），仅供参考