企业官网建设流程全解析

• 前端
• 静态站点

本篇技术指南围绕 minimal-mistakes Jekyll 主题中"文章摘要图（teaser）与社交分享图（og_image）分离配置"这一场景展开，以官方示例文章 post-teaser-image-og-override.md 为骨架，深入解读 YAML Front Matter 的写法、seo.html 中 Open Graph / Twitter Card 元数据的生成优先级，以及网格归档视图对 teaser 的实际渲染方式。读完本文，你将掌握如何在文章列表页显示专属缩略图、在社交平台分享时展示另一张更合适的大图，并理解站点级默认图片的回退机制。

一、示例文章剖析：Teaser + OpenGraph 双重图片声明

minimal-mistakes 的官方示例 post-teaser-image-og-override.md 全文极短，核心就是一段 Front Matter 和一句说明，但它演示了一个非常重要的能力：列表页用一张图，社交分享用另一张图。

--- title: "Post: Teaser Image with OpenGraph Override" header: teaser: /assets/images/page-header-teaser.png og_image: /assets/images/page-header-og-image.png categories: - Layout - Uncategorized tags: - edge case - image - layout last_modified_at: 2017-10-26T15:12:19-04:00 ---

两个关键字段：

示例中teaser使用page-header-teaser.png（示例文件，400×300 规格），og_image使用page-header-og-image.png（示例文件，1600×800 规格），两者刻意使用不同图片以验证"覆盖"（override）行为。

该示例在test/目录下也有对应副本 test/_posts/2010-08-05-post-teaser-image-og-override.md，供主题开发者回归验证。

二、Teaser 图片：归档视图的缩略图渲染逻辑

header.teaser并非页面正文的一部分，它只影响**归档视图（archive）**的展示。查看 archive-single.html 的源码可以确认这一点：

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

随后在网格布局（include.type == "grid"）中才真正输出图片元素：

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

从源码结构可以推断出三个要点：

1. teaser 只在grid类型的归档视图渲染。列表视图（list）只输出标题、日期和摘要，不渲染 teaser 图片；这与docs/_docs/10-layouts.md中关于归档布局的说明一致。
2. 未设置header.teaser时，回退到站点级site.teaser（同样定义于 _config.yml）。
3. 图片通过relative_url输出，因此建议使用以/assets/images/开头的绝对站点路径。

三、OpenGraph 覆盖：seo.html 中的图片优先级链

og_image的核心作用在 _includes/seo.html 中体现得最为直接。该文件是 minimal-mistakes 的 SEO 元数据生成器，其第 29–32 行定义了三级图片优先级：

{%- assign page_large_image = page.header.og_image | default: page.header.overlay_image | default: page.header.image | absolute_url | escape -%} {%- assign page_teaser_image = page.header.teaser | default: site.og_image | absolute_url | escape -%} {%- assign site_og_image = site.og_image | absolute_url | escape -%} {%- assign og_image_alt = page.header.og_image_alt | default: site.og_image_alt | escape -%}

由此可以得到完整的图片解析优先级：

大图（page_large_image）—— 决定社交分享主图：

1. page.header.og_image（本页 Front Matter 显式指定，优先级最高）
2. page.header.overlay_image（overlay 头图）
3. page.header.image（普通头图）

也就是说，只要设置了og_image，无论页面有没有头图，分享卡片都会用它。这正是示例文章标题中 "Override"（覆盖）一词的由来——用一张专用图片覆盖默认从头图继承来的分享图。

小图（page_teaser_image）—— 备用分享图：

1. page.header.teaser
2. site.og_image（站点级默认）

page_teaser_image只在大图为空时才兜底输出（见 seo.html 第 60–70 行）：

{% if page_large_image %} <meta property="og:image" content="{{ page_large_image }}"> {% elsif page_teaser_image %} <meta property="og:image" content="{{ page_teaser_image }}"> {% endif %}

输出到哪些 Meta 标签

当page_large_image存在时（seo.html 第 78–83 行），Twitter Card 会升级为summary_large_image大图卡片：

{% if page_large_image %} <meta name="twitter:card" content="summary_large_image"> <meta name="twitter:image" content="{{ page_large_image }}"> {% else %} <meta name="twitter:card" content="summary"> {% if page_teaser_image %} <meta name="twitter:image" content="{{ page_teaser_image }}"> {% endif %} {% endif %}

同时 Facebook 侧始终输出：

<meta property="og:type" content="article"> <meta property="og:image" content="..."> <meta property="og:image:alt" content="...">

Alt 文本机制

og_image_alt用于为分享图片提供无障碍描述（seo.html 第 32、62–63 行）：

header: og_image: /assets/images/your-og-image.jpg og_image_alt: "Description of the image"

它同时作用于og:image:alt与twitter:image:alt两个标签，且优先于站点级site.og_image_alt（定义于 _config.yml 第 98–99 行）。如果两者都未设置，则 alt 标签整体省略。

四、站点级默认：site.og_image与site.og_image_alt

在 _config.yml 中可以配置全站默认的分享图：

og_image : # Open Graph/Twitter default site image og_image_alt : # Alt text for Open Graph/Twitter default site image

主题文档站点的实际配置见 docs/_config.yml：

og_image : "/assets/images/site-logo.png" # Open Graph/Twitter default site image og_image_alt : "Site logo"

根据 docs/_docs/05-configuration.md 中的说明，站点级og_image作为兜底图有明确的使用建议：适用于没有在 Front Matter 中声明任何header.image的页面；推荐使用 Logo、头像或站点标识，文件需放在/assets/images/目录下，最小 120×120 像素、体积小于 1MB。

三种配置的生效关系可以概括为：

五、配套示例与综合实践

1. 与头图（header image）配合

官方还提供了两个配套示例，展示og_image如何覆盖头图：

• post-header-image-og-override.md：页面设置了header.image，同时用og_image+og_image_alt覆盖分享图；
• post-header-overlay-image-og-override.md：页面使用overlay_image时同样可以覆盖。

综合完整写法如下：

--- title: "My Post" header: image: /assets/images/your-page-image.jpg og_image: /assets/images/your-og-image.jpg og_image_alt: "Description of the image" ---

2. 给没有头图的页面设置分享图

docs/_docs/10-layouts.md 中特别指出一个 ProTip：og_image对没有头图或 overlay 图的页面尤其有用。例如一个纯文本的 FAQ 页面，可以这样写：

--- title: "FAQ" header: teaser: /assets/images/faq-thumb.png og_image: /assets/images/faq-og.png og_image_alt: "FAQ overview" ---

这样归档列表显示小缩略图faq-thumb.png，而分享到社交平台时则使用专门设计的横向大图faq-og.png。

3. 验证与调试

• 本地构建：bundle exec jekyll serve后查看页面源码，检索og:image与twitter:image标签确认输出值；
• Facebook 官方调试工具可抓取并刷新页面元数据；若修改后分享缓存未更新，需手动触发重新抓取；
• 注意 seo.html 中图片均经过absolute_url处理，请确保_config.yml中url/baseurl配置正确，否则生成的绝对地址可能不完整。

六、小结

通过header.teaser与header.og_image两个 Front Matter 字段，minimal-mistakes 允许站点作者把"归档缩略图"和"社交分享图"彻底解耦：

• teaser决定列表/网格归档视图的小图，缺失时回退site.teaser；
• og_image决定 Open Graph 与 Twitter Card 的大图，优先级高于overlay_image与image，缺失时依次回退到页面头图、teaser 再到站点级site.og_image；
• og_image_alt与站点级og_image_alt共同构成 alt 文本的覆盖链。

这套机制的全部行为都可在 _includes/seo.html 与 _includes/archive-single.html 中直接读到源码依据，官方示例 post-teaser-image-og-override.md 则是最简洁的"开箱即用"模板，直接复制其 Front Matter 结构即可应用到自己的文章上。

• 前端
• 静态站点