Hugo Blox Bootstrap 博客文章 Archetype 全解：从 Front Matter 配置到渲染机制

• 静态站点
• 前端
• 开发工具

导读

本文以 blox-bootstrap 模块的博客文章 Archetype 为骨架，系统讲解在 Hugo Blox 中创建博客文章所需的全部 Front Matter 字段、图片配置与项目关联机制，并结合 card.html、page_header.html 与 get_featured_image.html 等源码，讲透这些配置从写入到渲染的完整链路。读完本文，你将能独立编写一份结构完整、图片策略正确、可被列表页与详情页正确解析的博客文章，并理解 Hugo Blox「Markdown 写内容、YAML 做配置」的核心工作流。

一、Archetype 是什么：新文章的"出生模板"

Hugo 的 Archetype（原型）是执行hugo new创建新内容时自动套用的 Front Matter 模板。在 blox-bootstrap 模块中，每个内容类型都配有独立的 Archetype：

• post/index.md —— 博客文章
• project/index.md —— 项目
• event/index.md —— 演讲/活动
• publication/index.md —— 学术出版物
• default.md —— 通用兜底

以post为例，当你执行：

hugo new blog/my-first-post/index.md

时，Hugo 会把 post/index.md 中的模板内容复制到新文件，并将{{ .Name }}、{{ .Date }}等模板变量替换为实际值，随后你在该骨架之上填充正文即可。

从源码结构看，Archetype 中的注释还保留了官方文档指引# Documentation: https://docs.hugoblox.com/managing-content/，说明该骨架的目标就是让你不必记忆字段，直接在新文件中按注释填写。

二、Front Matter 字段逐项拆解

Archetype 定义了博客文章的全部可选元数据字段，按功能可以分为五组。下面逐一说明含义、类型与默认值。

2.1 基本信息组

title: "{{ replace .Name "-" " " | title }}" subtitle: "" summary: "" authors: [] tags: [] categories: [] date: {{ .Date }} lastmod: {{ .Date }} featured: false draft: false

其中title使用了 Hugo 模板语法{{ replace .Name "-" " " | title }}——创建文件时文件名中的-会被替换为空格并转为首字母大写，因此建议新文章用kebab-case命名（如my-first-post），自动生成的标题即为My First Post。

2.2 特色图片组（Featured Image）

# Featured image # To use, add an image named `featured.jpg/png` to your page's folder. # Focal points: Smart, Center, TopLeft, Top, TopRight, Left, Right, BottomLeft, Bottom, BottomRight. image: caption: "" focal_point: "" preview_only: false

图片文件放置规则：默认约定是在文章所在目录放一张名为featured.jpg或featured.png的图片。若需要更灵活的文件名，可以在image下额外指定filename字段（Archetype 虽未显式列出，但 get_featured_image.html 支持该字段，见下文源码验证）。

2.3 项目关联组

# Projects (optional). # Associate this post with one or more of your projects. # Simply enter your project's folder or file name without extension. # E.g. `projects = ["internal-project"]` references `content/project/deep-learning/index.md`. # Otherwise, set `projects = []`. projects: []

projects将博客文章与一个或多个项目页关联。填写时只需给出项目目录名（不含扩展名），例如projects: ["deep-learning"]会关联content/project/deep-learning/index.md。关联后，文章页会显示项目链接，项目页也会在相关页面区域回显这些文章，形成内容之间的双向引用网络。

三、源码验证：这些配置如何驱动渲染

Archetype 只是"入口"，真正的行为逻辑在布局模板中。我们以三个关键文件印证配置的实际效果。

3.1 特色图片的查找顺序

get_featured_image.html 的注释明确定义了三步查找优先级：

1. 在文章目录中查找文件名匹配*featured*的图片（即featured.jpg/png等）；
2. 未找到时，查找image.filename指定的文件（先在文章目录内）；
3. 仍未找到时，回退到全局assets/media/目录中查找同名文件。

这意味着即使你不遵循featured.jpg命名规范，也可以通过image.filename: my-cover.webp显式指定特色图，甚至把图片统一放在站点的assets/media/目录集中管理。该 partial 返回的是 Hugo 的图片资源对象（Resource），供后续裁剪与处理。

3.2 列表卡片：摘要与图片裁剪

card.html 是博客列表页渲染每篇文章卡片的模板，它体现了summary与focal_point的实际用法：

• 摘要优先级（第 14-21 行）：先取 Front Matter 的summary，其次取abstract（出版物专用），最后回退到 Hugo 自动摘要$item.Summary。因此显式填写summary可以精确控制列表卡片上的文案，避免自动截断。
• 焦点裁剪（第 44-48 行）：$anchor := $item.Params.image.focal_point | default "Smart"，即focal_point为空时默认按Smart智能裁剪；随后执行.Fill "808x455"将特色图统一裁剪为 808×455 的卡片比例，非 GIF 图片还会转为 WebP 以减小体积。

这解释了为什么列表页所有卡片图片都是统一尺寸——并非原图如此，而是渲染期裁剪的结果。文章图片选择时应保证主体内容居中或符合所选焦点方向，避免裁剪后丢失关键信息。

3.3 文章详情页：preview_only 与图片布局

page_header.html 是文章详情页头部：

• 第 42 行条件if and $featured (not .Params.image.preview_only)：当存在特色图且preview_only为false时，才在详情页展示大图。若设置preview_only: true，图片只出现在列表卡片上，详情页头部则跳过图片区块——适合封面不适合作为文章头图（如包含文字水印的社交分享图）的场景。
• 第 48-60 行：image.placement控制图片宽度布局，取值1（默认，居中article-container，Fit 720x2500）、2（container容器宽度，Fit 1200x2500）、3（container-fluid全宽，Fit 2560x2560）。
• 第 66-68 行：subtitle会渲染在<h1>下方作为页面副标题。
• 图片输出前同样执行Process "webp"转换，保证现代浏览器下的加载性能。

四、真实示例：starter 中的完整博客文章

仓库的 blog starter 提供了可直接对照的成品案例。以 get-started/index.md 为例：

--- title: 🎉 Easily create your own simple yet highly customizable blog summary: Take full control of your personal brand and privacy by migrating away from the big tech platforms! date: 2023-10-27 # Featured image # Place an image named `featured.jpg/png` in this page's folder and customize its options here. image: caption: 'Image credit: [**Unsplash**](https://unsplash.com)' authors: - admin - Ted tags: - Academic - Hugo Blox - Markdown ---

这份真实文章的字段使用与 Archetype 完全对应：summary给出了精炼的列表摘要，image.caption支持 Markdown 链接，多作者通过authors列表声明。starter 中其余文章（如>cascade: - _target: path: /blog/** kind: page pager: true editable: true hide_date: false show_date_updated: true reading_time: true commentable: true show_related: true share: true

这意味着reading_time、show_related、share等展示开关可以按内容分区批量配置，不必在每个文章 Front Matter 中重复书写——Archetype 负责"单篇骨架"，cascade负责"批量默认值"，两者配合构成完整的文章创建体系。

五、与其他内容类型的 Archetype 对比

理解postArchetype 后，对比同模块的其他 Archetype 可以更快掌握 Hugo Blox 的内容组织哲学：

• default.md 与post字段几乎完全一致，是普通页面的兜底模板；
• project/index.md 在post基础上增加了external_link（跳转外部 URL 替代详情页）、url_code/url_pdf/url_slides/url_video（按钮链接组）和slides（关联 Reveal.js 幻灯片），且没有draft、lastmod字段；
• event/index.md 则围绕演讲/活动场景设计。

可以看出：postArchetype 刻意保持精简——它只包含通用元数据、图片与项目关联，把url_*按钮、links自定义链接等更专用的字段留给project、publication等类型。这是 Hugo Blox 的设计取舍：博客文章的重心在正文内容，而非外部链接装饰。

六、实战操作清单

综合以上分析，在 Hugo Blox（blox-bootstrap 模块）下创建一篇规范的博客文章，推荐流程如下：

1. 创建文件：在content/blog/下执行hugo new blog/my-post/index.md（或直接用编辑器新建），获得 post Archetype 生成的骨架；
2. 填写元数据：按 2.1 节的表格填写title、summary、authors、tags、categories，删除不用的字段或保持默认值；
3. 准备特色图：在文章目录放置featured.jpg/png，或在image.filename指定自定义文件名；根据裁剪规则选择focal_point（主体偏上选Top、居中选Center，拿不准就用默认Smart）；
4. 决定图片展示策略：若图片只在列表页需要，设preview_only: true；需要大图展示时，按需配置image.placement: 1|2|3与image.caption；
5. 关联项目（可选）：填写projects列表，形成文章与项目页的双向关联；
6. 发布控制：写作期间保持draft: true本地预览，完成后改为false再提交构建。

七、注意事项与最佳实践

• 命名即标题：{{ .Name }}模板会把文件名转成标题，用kebab-case命名新文章，避免标题中出现连字符；
• 显式摘要优于自动截断：summary为空时，列表页会回退到正文自动摘要（summaryLength等参数受 hugo.yaml 控制），显式填写可在列表页呈现精心设计的导语；
• 图片体积：所有列表卡片图片都会被渲染期统一裁剪为 808×455 并转 WebP，上传原图时仍应尽量压缩，避免拖慢构建与首屏；
• preview_only与详情页头图是独立开关：想在详情页显示与列表缩略图不同的图，可以结合image.filename+preview_only组合使用；
• 草稿隔离：draft: true的文章在本地hugo server可见，但发布构建不会输出，适合进行中的创作；
• 全局默认值下沉到 cascade：批量性的展示开关优先放 hugo.yaml 的cascade，保持每篇文章 Front Matter 精简可读。

从 Archetype 的字段定义，到 get_featured_image.html 的查找逻辑，再到 card.html 与 page_header.html 的渲染行为，一条「配置 → 资源解析 → 裁剪 → 展示」的完整链路清晰可见。掌握这份 post/index.md 骨架，你就能以极低的成本持续产出结构规范、视觉统一、可被列表页与详情页正确渲染的博客内容——这正是 Hugo Blox「用 Markdown 拥有你的内容」这一理念在内容创作环节的具体落地。

• 静态站点
• 前端
• 开发工具