# 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）

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

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

```yaml
---
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', '网络']
---
```


---

> 作者: [Higer](https://higer.ren/)  
> URL: https://higer.ren/docs/hugo-fixit-front-matter-reference/