Hugo + FixIt Front Matter 速查表

本表汇总 higer.ren 站点（Hugo 0.169 + FixIt v1.0.0-rc）可用的 front matter 属性，分「通用 Hugo」「FixIt 专属」「本站点约定」三类。所有 FixIt 字段均已对照主题 themes/FixIt/layouts 源码核实，不是凭记忆。

提示：FixIt 会读取 front matter 的 title 渲染页面 H1，正文不要再写同名 # 标题，否则页面出现两个大标题。

一、通用 Hugo 属性（所有页面可用）

字段	类型	默认	说明
`title`	string	—	页面标题（必填）；FixIt 渲染为 H1
`date`	date/datetime	—	发布日期；决定 `/docs/` 年份分组与排序
`lastmod`	date/datetime	—	最后修改时间；影响「更新于」展示
`draft`	bool	`false`	草稿开关：`true` = 不发布（本地需 `hugo -D` 才可见），`false` = 正常发布
`slug`	string	文件名	自定义 URL 片段；中文文件名务必配英文 slug，避免 URL 被百分号编码
`aliases`	array(string)	—	旧路径 → 新路径重定向，改名后旧链接不 404
`description`	string	—	SEO 描述（meta），也作为列表摘要的兜底（除非写 `summary`）
`categories`	array(string)	—	分类（Hugo taxonomy）
`tags`	array(string)	—	标签（taxonomy）
`keywords`	array(string)	—	SEO 关键词
`weight`	int	0	排序权重，越小越靠前；FixIt 中 ≥1 可在首页置顶（见第三节）
`url`	string	—	强制 URL（极少用）
`outputs`	array(string)	—	自定义输出格式
`layout`	string	—	强制使用某模板
`resources`	array	—	页面捆绑资源（图片等，配合 `images`）
taxonomy 词	—	—	本站点已注册 `authors` taxonomy（见 `hugo.toml` 的 `[taxonomies]`）

二、FixIt 专属属性（本主题支持，已核实源码）

字段	类型	默认	说明
`featured_image`	string	—	文章/文档封面图（FixIt 经 `get-cover.html` 读取此字段，非 `images` 也非 `featuredImage`）；填静态路径如 `/images/xxx.svg`，主题博客页原生渲染，文档页由本站 `layouts/docs/single.html` 覆盖渲染
`images`	array(string)	—	社交分享 / OG 图源（head 模板读取），与 `featured_image` 分工不同
`toc`	map	继承站点	单页覆盖站点 `[params.toc]`，如 `toc: { enable: false }` 关掉某页目录；子键：`enable` / `start_level` / `end_level` / `position` / `auto` / `ordered` / `keep_static`
`summary`	string	取首段	自定义列表卡片摘要（覆盖默认首段截取）
`summary_placeholder`	string	—	无摘要时的占位文案
`lightgallery`	bool	`true`	图片点击放大灯箱
`comment`	bool	站点默认	评论开关（需先接入评论系统才有效）
`share`	bool	`true`	分享按钮
`reward`	bool	`true`	打赏（知识/文档站一般设 `false`）
`license`	string/bool	站点默认	单页版权声明，覆盖全站默认
`editURL`	string	—	「编辑此页」链接
`math`	bool	`false`	KaTeX 数学公式
`mermaid`	bool	`false`	Mermaid 流程图 / 时序图
`diagram`	bool	`false`	架构图等
`echarts`	bool	`false`	数据图表
`audio`	string/map	—	音频嵌入
`video`	string/map	—	视频嵌入
`bilibili` / `youtube` / `dplayer`	string	—	视频平台嵌入
`mapbox`	map	—	地图
`hiddenFromHomePage`	bool	`false`	不进首页文章卡片
`hiddenFromSearch`	bool	`false`	不进站内搜索索引

说明：comment / share / reward / math 等开关在主题里既读站点 [params.xxx] 也读页面 front matter，页面级可单独开/关。

三、本站点约定（higer.ren）

docs 区模板 archetypes/docs.md 默认值：title(自动) / date / lastmod / draft: false / slug / weight: 0 / description / categories: ['文档'] / tags: [] / keywords: []。
标题只放 front matter，正文不写 # H1（避免重复大标题，与 hugo-fixit 本地开发速查、water-tracker-design-spec 等现有文档一致）。
weight 语义：0 = 不置顶；≥1 在首页置顶（数字越小越靠前）；/docs/ 列表按年份分组，weight 对它无效。
中文文件名必须配英文 slug，否则 URL 出现 %xx 乱码。
文档默认进首页卡片 + 搜索；如需排除用 hiddenFromHomePage / hiddenFromSearch。

四、最小可用模板（docs）

---
title: '文档标题'
date: 2026-11-08
lastmod: 2026-11-08
draft: false
slug: english-slug
description: '一句话摘要，用于 SEO 与列表卡片'
categories: ['文档']
tags: ['标签1', '标签2']
---

五、进阶示例（封面图 + 关目录 + 关打赏）

---
title: '某硬核文档'
date: 2026-11-08
lastmod: 2026-11-08
draft: false
slug: some-doc
description: '带架构图与公式的技术文档示例'
images: ['/images/cover.jpg']   # 封面图 / 社交分享图
toc: { enable: false }          # 单页关闭页内目录
reward: false                   # 文档站关闭打赏
comment: false                  # 未接评论系统，显式关闭
tags: ['NAS', '网络']
---