Hugo Blox Bootstrap 内容模板(Archetype)深度解析:掌握 `default.md` 与全套 Front Matter 配置
Hugo Blox Bootstrap 内容模板(Archetype)深度解析:掌握 default.md 与全套 Front Matter 配置
导读
在 Hugo Blox Bootstrap 主题中,hugo new 创建内容文件时使用的模板被称为 Archetype(内容原型)。modules/blox-bootstrap/archetypes/default.md 是所有"常规页面"(博客文章、普通页面等)的默认 Front Matter 骨架,它决定了每篇内容从创建之初就具备标题、作者、标签、摘要、精选图片、关联项目等标准字段。本文将以该文件为绝对主线,逐一拆解每个 Front Matter 参数的含义、默认值与用法,并结合仓库内其他内容模板(book.md、home.md、event、project、publication、slides、authors)与主题模板源码,说明这些参数最终如何被 Hugo Blox Bootstrap 的布局系统消费,帮助你写出规范、可被主题完整渲染的内容。
一、Archetype 是什么:Hugo 的内容创建机制
Hugo 在运行 hugo new content/posts/my-post.md(或 hugo new posts/my-post.md)时,会按以下优先级查找模板:
- 当前站点
archetypes/目录下的模板; - 被引入的主题/模块中对应内容的 Archetype(本仓库中即 modules/blox-bootstrap/archetypes/);
- 回退到 Hugo 内置的默认模板。
模板文件名遵循 content type 优先 的规则:archetypes/post.md 匹配 content/post/** 下的内容;archetypes/default.md 则是兜底的通用模板,当某个类型没有专属模板时自动生效。这就是为什么 modules/blox-bootstrap/archetypes/default.md 如此重要——它是绝大多数普通内容创建的默认起点。
模板文件中的 Go Template 语法
default.md 中使用了两个 Hugo 模板函数:
title: "{{ replace .Name "-" " " | title }}"
.Name:新建文件的文件名(不含扩展名);replace .Name "-" " ":把文件名中的连字符替换为空格(如my-first-post→my first post);| title:将字符串转换为 Title Case(my first post→My First Post)。
date: {{ .Date }} 则自动填充当前时间戳。这意味着你几乎不需要在创建后手动补写标题与日期——Hugo 已经基于文件名和当前时间生成了合理的初值。
二、default.md Front Matter 逐字段详解
以下是对 modules/blox-bootstrap/archetypes/default.md 全部字段的完整解读(默认值即为模板中呈现的值)。
1. 基础信息字段
| 字段 | 默认值 | 说明 |
|---|---|---|
title |
文件名自动转换 | 页面标题,建议保留双引号包裹 |
subtitle |
"" |
副标题,显示在主标题下方 |
summary |
"" |
内容摘要,用于列表页卡片、RSS 与社交媒体分享摘要 |
authors |
[] |
作者用户名列表,需与 content/authors/ 下的作者目录名一致 |
tags |
[] |
标签列表,用于 tags 聚合页 |
categories |
[] |
分类列表,用于分类聚合页 |
date |
{{ .Date }} |
创建时间,控制内容的发布时间 |
lastmod |
{{ .Date }} |
最后修改时间,Hugo 会自动更新 |
featured |
false |
是否为精选内容(true 会在列表中优先/突出展示) |
draft |
false |
是否为草稿;true 时在未加 -D/--buildDrafts 参数构建时不会发布 |
lastmod在 Hugo Blox 中建议保留,它与 modules/blox-bootstrap/layouts/partials/page_metadata.html 渲染的"更新日期"直接相关。
2. Featured Image:精选图片配置
# To use, add an image named `featured.jpg/png` to your page's folder.
image:
caption: ""
focal_point: ""
preview_only: false
这是 Hugo Blox 系列主题的特色能力:不需要手工写 <img> 标签,只要在内容目录中放置一张名为 featured.jpg 或 featured.png 的图片,主题就会自动拾取并渲染。
| 参数 | 默认值 | 说明 |
|---|---|---|
caption |
"" |
图片说明文字(图注) |
focal_point |
"" |
焦点位置,可选 Smart、Center、TopLeft、Top、TopRight、Left、Right、BottomLeft、Bottom、BottomRight |
preview_only |
false |
true 时图片仅在列表/预览中显示,不在详情页正文顶部展示 |
focal_point 并非摆设:主题在裁剪缩略图时会以该点作为裁剪中心。从源码看,该参数在 modules/blox-bootstrap/layouts/partials/views/card.html(列表卡片视图)与 modules/blox-bootstrap/layouts/partials/page_header.html(详情页头部)中被读取,用于生成按焦点定位的响应式图片。默认值 Smart 表示由图片处理管线根据图像内容自动判断视觉焦点。
3. Projects:内容与项目的关联
# 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: ["internal-project"] 对应 content/project/deep-learning/index.md。
该字段的消费逻辑分布在多个模板中:例如 modules/blox-bootstrap/layouts/project/single.html、modules/blox-bootstrap/layouts/partials/functions/has_attachments.html 与 modules/blox-bootstrap/layouts/partials/page_links.html 都会检查 page.Params.projects,用来在页面中渲染"所属项目"链接或附件按钮。不打算关联项目时保持 [] 即可。
三、从 default.md 出发:blox-bootstrap 全套内容模板图谱
default.md 是通用兜底模板,而 modules/blox-bootstrap/archetypes/ 目录下还按内容类型细分了多个专用模板,理解它们的差异能让你为不同类型的页面选择正确的起点:
1. post / event / project / publication:列表型内容
- archetypes/post/index.md:与
default.md几乎一致,用于博客文章,是default.md的直接子集; - archetypes/event/index.md:讲座/活动页面,额外包含
event、event_url、location、address(street/city/region/postcode/country)、abstract、date_end、all_day、publishDate、url_slides/url_code/url_pdf/url_video、slides等字段,用于渲染活动的时间地点信息; - archetypes/project/index.md:项目页面,包含
external_link(可让项目详情页直接跳转到外部 URL)、url_code/url_pdf/url_slides/url_video、slides; - archetypes/publication/index.md:学术出版物页面,包含
doi、publishDate、publication_types(编码表:0 = Uncategorized; 1 = Conference paper; 2 = Journal article; 3 = Preprint; 4 = Report; 5 = Book; 6 = Book section; 7 = Thesis; 8 = Patent)、publication、publication_short、abstract、url_dataset/url_poster/url_project/url_source等。
2. book / home / slides / authors:特殊页面模板
- archetypes/book.md:文档书籍页,设置
type: book并附带linktitle,配合主题的 book 相关布局 使用; - archetypes/home.md:首页区块模板,使用 TOML 格式而非 YAML,声明
widget = "blank"、headless = true、active = true、weight,并支持[design.background](背景色/渐变/图片)、[design.spacing](内边距)、[advanced](自定义 CSS)等区块设计参数——它是 Hugo Blox 页面构建器(Page Builder)的核心入口,每个首页区块对应一个这样的文件; - archetypes/slides/index.md:Markdown 幻灯片页面,包含
slides.theme(Reveal.js 主题,默认black)、highlight_style(默认dracula)、diagram(Mermaid 图表)、reveal_options(controls、progress、slide_number、transition 等); - archetypes/authors/_index.md:作者档案模板,包含
superuser、role、organizations、bio、interests、education.courses、social(envelope/twitter/google-scholar/github 等图标)、email、highlight_name、user_groups,是个人主页与作者卡片的数据来源。
四、实战:用默认模板创建一个标准文章
假设你在使用任意一个基于 blox-bootstrap 的 starter(如仓库中的 starters/academic-cv),创建一篇新文章只需:
hugo new content/post/my-first-post.md
Hugo 会套用 modules/blox-bootstrap/archetypes/post/index.md(post 类型专用模板,结构与 default.md 一致),自动生成类似下面的文件:
---
title: "My First Post"
subtitle: ""
summary: ""
authors: []
tags: []
categories: []
date: 2026-09-23T07:31:20+08:00
lastmod: 2026-09-23T07:31:20+08:00
featured: false
draft: false
image:
caption: ""
focal_point: ""
preview_only: false
projects: []
---
随后按需填充即可:
---
title: "My First Post"
summary: "这是我在站点上的第一篇文章"
authors: [admin]
tags: [hugo, blox]
categories: [tutorial]
date: 2026-09-23T07:31:20+08:00
lastmod: 2026-09-23T07:31:20+08:00
featured: true
draft: false
image:
caption: "我的文章封面"
focal_point: "Center"
preview_only: false
projects: ["internal-project"]
---
这里是正文,支持 Markdown 语法。
几个实战要点:
- 草稿控制:
draft: true的内容在本地预览hugo server时仍会显示(Hugo 默认构建草稿,但生产构建hugo不会),发布前记得改回false,或使用hugo --buildDrafts强制构建草稿; - 作者关联:
authors: [admin]中的admin必须与content/authors/admin/目录名一致,否则无法关联到作者档案页; - 图片命名:在文章目录(如
content/post/my-first-post/)放一张featured.jpg或featured.png,主题会自动拾取并应用focal_point与caption配置; - 本地预览:
hugo server启动后访问http://localhost:1313即可看到渲染结果。
五、原理纵深:模板参数如何被主题消费
Hugo Blox Bootstrap 中 Front Matter 并非"写了就算",而是被主题的模板系统真实读取。以下两条调用链可以直接在仓库源码中验证:
图片焦点(focal_point)调用链:内容参数 image.focal_point 在 modules/blox-bootstrap/layouts/partials/views/card.html 和 modules/blox-bootstrap/layouts/partials/page_header.html 中被读取,传给图片处理函数生成带焦点定位的缩略图与页头图,最终由 modules/blox-bootstrap/layouts/_default/single.html 等页面骨架整合输出。
项目关联(projects)调用链:page.Params.projects 在 modules/blox-bootstrap/layouts/project/single.html、modules/blox-bootstrap/layouts/partials/functions/has_attachments.html 与 modules/blox-bootstrap/layouts/partials/page_links.html 中被检查,用于在文章/出版物页面渲染"所属项目"链接或相关附件入口。
日期(lastmod)调用链:lastmod 在 modules/blox-bootstrap/layouts/partials/page_metadata.html 中被读取,用于在页面元信息区显示"最后更新"时间。
理解这些调用关系,你就能预判"改某个 Front Matter 字段会在页面上产生什么效果",从而避免无效配置。
六、常见问题与最佳实践
- 为什么
hugo new生成的标题带连字符? 因为模板中的{{ replace .Name "-" " " | title }}依赖文件名生成标题,如果你用下划线或驼峰命名文件,建议创建后手动修正title。 preview_only: true会怎样? 图片只出现在列表/卡片预览中,详情页正文顶部不再展示大图,适合封面与内容无关的场景。- 哪些字段可以安全删除?
featured、preview_only、projects等均带默认值(false/[]),不涉及该功能时可删除或留空;但title、date建议保留,它们是 Hugo 排序与渲染的基础。 - 最佳实践清单:始终保留
draft: true直到内容就绪;用summary而非截断正文来控制列表摘要;图片统一命名为featured.*;作者名严格对应content/authors/目录。
结语
modules/blox-bootstrap/archetypes/default.md 虽然只有短短几十行,却是 Hugo Blox Bootstrap 内容体系的基石:它定义了内容创建的默认契约,而 post、event、project、publication、book、home、slides、authors 等专用模板则在此基础上按内容类型扩展字段。掌握了这份模板及其参数在 模块布局 中的消费方式,你就能在 hugo new 之后用最少的编辑产出结构规范、渲染完整的内容页面。