Front Matter CMS

本指南系统说明如何在本 Hugo 多语言站点中使用 VS Code 插件 Front Matter CMS 完成日常内容创作、分类管理、片段复用与（可选的）国际化配置。

适用读者¶

需要以更友好 UI 管理 Markdown 内容的贡献者
想了解 frontmatter.json 配置结构的开发者
负责维护内容模型（内容类型、字段、工作流）的站点管理员

插件安装¶

打开 VS Code 扩展市场搜索 Front Matter。
安装后第一次启动项目会在工作区根目录自动读取或创建 frontmatter.json。
侧栏会出现 Front Matter 图标；点击进入 Dashboard。

核心概念概览¶

概念	本项目对应	说明
Content Types	`frontMatter.taxonomy.contentTypes`	定义字段结构与表单生成方式
Page Folders	`frontMatter.content.pageFolders`	定位内容根路径并绑定允许的 Content Types
Preview Host	`frontMatter.preview.host`	预览按钮打开的本地站点地址
Snippets	`frontMatter.content.snippets`	可插入的 Shortcode/片段模板
Auto Update Date	`frontMatter.content.autoUpdateDate`	保存时自动写入/更新日期字段

配置文件结构 (`frontmatter.json`)¶

主要顶层键：

$schema：用于 VS Code 提示的 JSON Schema URL。
frontMatter.taxonomy.contentTypes：数组，每个对象描述一个内容类型（名称、是否 page bundle、预览路径、字段列表）。
frontMatter.content.pageFolders：绑定物理目录与可使用的内容类型。
其它：preview.host、website.host、framework.*、content.snippets 等。

示例：内容类型片段（简化）¶

{
  "name": "blog",
  "pageBundle": true,
  "previewPath": "blog/",
  "fields": [
    { "title": "title", "name": "title", "type": "string" },
    { "title": "date", "name": "date", "type": "datetime" },
    { "title": "tags", "name": "tags", "type": "tags" }
  ]
}

字段类型常见值¶

string / datetime / number / boolean
draft（插件内置布尔草稿类型）
tags（标签编辑器）
choice（枚举下拉；multiple 控制多选）
image（图片选择器）

Page Folders 绑定¶

一个 Page Folder 指定：

title：在 CMS Dashboard 显示名称
path：物理路径，可用 [[workspace]] 占位符
contentTypes：允许在该路径下创建的类型集合

示例：

{
  "title": "blog",
  "path": "[[workspace]]/content/zh/blog",
  "contentTypes": ["blog"]
}

内容创建流程¶

在 Dashboard 选择目标 Page Folder（如 blog）。
点击“Create” → 选择 Content Type（若只绑定一个将直接出现表单）。
填写字段并保存，插件会生成对应目录下的 index.md（若 pageBundle=true）或 .md 文件。
使用“Open Preview”或浏览器访问 http://localhost:1313/<previewPath>/<slug>/ 进行预览。

Snippets（片段）¶

frontMatter.content.snippets 提供可插入模板，常用于 Shortcode：

在 Markdown 编辑器中使用 Front Matter 面板的 Snippet 插入。
本项目已包含：SlideEmbed、Bilibili、Markmap、IncludeCode、Details、CalloutNote、CTA、TableWrapper、ListChildren、PodcastEmbed。

示例（Callout）：

{{< callout note "可选标题" >}}
正文内容…
{{< /callout >}}

国际化（i18n）模式说明¶

当前仓库采用“分离式多语言”策略：

中文与英文使用独立目录与独立 content types（如 blog 与 blog-en）。
没有使用 defaultLocale + locales 合并模式，避免 Dashboard 过滤结果缺失。

如果未来需要切换到“统一式”聚合 i18n：

去除 *-en 内容类型，保留一套中性类型。
在默认语言目录（例如 zh）对应 Page Folder 上添加：

"defaultLocale": "zh",
"locales": [
  { "locale": "zh", "title": "中文", "path": "" },
  { "locale": "en", "title": "English", "path": "../../en/blog" }
]

仅保留另一语言的实际目录（可移除其单独的 Page Folder 配置）。
重新加载 VS Code，使用 Dashboard locale 过滤与翻译操作。
逐步在每篇内容的 Front Matter 中添加 translationKey（如插件支持自动生成）。

注意：混合“分离式 content types + 局部 locales”会导致过滤不完整，需二选一模式。

工作流与最佳实践¶

目标	建议动作
新建文章	使用 Dashboard -> Create，避免手写 Front Matter 漏字段
批量更新 lastmod	启用 `autoUpdateDate`，或脚本批处理
添加字段	修改对应 content type `fields`，保持中英类型字段对齐
引入新分类枚举	在 `choice.choices` 中追加；保持中英版本语义对应
插入常用组件	使用 snippets 统一格式

版本控制¶

修改 frontmatter.json 后建议单独提交，附说明。
字段删除前先全局搜索，避免已有内容失去数据入口。

常见问题 (FAQ)¶

问题	原因	解决
Locale 过滤结果过少	混合部分 i18n 配置	回滚 locales 或完成统一式重构
字段不显示	`fields` 中 name 与文件现有字段不一致	修正 name 或重新创建文档让表单生成
Snippet 未出现	未重载配置或键名冲突	重启 VS Code 或检查 JSON 键唯一性

安全与一致性¶

避免在生产分支直接大规模 schema 变更；先在分支实验。
新字段尽量向后兼容（提供 default）。
枚举值命名稳定，避免内容历史失效。

迁移到统一式 i18n 的检查清单（可选）¶

备份当前 frontmatter.json。
设计目标 content types（去掉 -en 后缀）。
为每个默认语言 Page Folder 添加 defaultLocale 与完整 locales。
删除英文 Page Folder 与对应 *-en types。
Reload VS Code；验证创建与过滤。
选取 1~2 篇内容测试翻译关联。
批量迁移剩余内容；记录脚本或步骤文档。

总结¶

Front Matter CMS 为本项目提供了结构化内容管理、片段复用与潜在 i18n 支撑。当前我们采用独立多语言模型以保持稳定；未来若需更紧密的跨语言协作，可按本指南的统一式方案迁移。通过规范的 content types、page folders 与 snippets 配置，可以显著降低手工错误并提升内容迭代效率。

References¶

Front Matter 官方文档：https://frontmatter.codes/
项目 README：/README.md
配置参考：docs/reference/configuration.md