内容模板

这里是写作模板的入口和选择说明，不是一篇文章，也不是目录页。正确用法是打开对应模板页，在「完整可复制文件」一节复制代码围栏里的全部内容，再粘贴到目标 Markdown 文件。不要直接复制模板页自身顶部的 frontmatter。

先选模板

你要写的内容	推荐模板	判断理由
新建一级分类或二级目录的自动文章入口	目录页模板	目录页只负责展示结构，不写正文，也不是文章。
普通技术文章、经验总结，没有更细的专用结构	通用文章模板	最安全、最通用的五段式结构，适合大多数主题。
别人可以照着命令复现并验证结果	技术教程模板	强制关注环境、版本、步骤、预期输出和排错。
项目完成或阶段结束后梳理过程与得失	项目复盘模板	从背景、约束、方案一直写到指标、结论和后续行动。
记录个人经历、感受或生活片段	生活随笔模板	结构更自由，同时提醒隐私和图片脱敏。
记录一道算法题的题意、证明和代码	算法题解模板	逼着自己补齐数据范围、正确性证明、复杂度和易错点。
记录域名、部署、评论、CDN 或博客配置变更	建站记录模板	强调环境、可回滚步骤、验证结果和敏感信息处理。

如果仍然拿不准，先用「通用文章模板」。不要为了使用某一个模板而硬套结构；内容与模板不匹配时，通用模板反而更清楚。

模板总览

模板	适合记录什么	目标文件示例	关键 frontmatter 差异
目录页模板	一级分类或子目录的文章目录	`docs/catalog/技术笔记.md` 或 `docs/catalog/技术笔记/项目记录.md`	使用 `layout: page`、`catalogue: true`、`path`、`pageTitle` 和 `/catalog/...` 永久链接；不能写 `date`、`categories`、`tags`、`top`、`sticky`。
通用文章模板	大多数普通文章	`docs/posts/技术笔记/10.example-article.md`	标准文章字段：`title`、`description`、`date`、`permalink`、`categories`、`tags`、`coverImg` 及四个文章开关。
技术教程模板	可复现的操作教程	`docs/posts/技术笔记/10.docker-tutorial.md`	文章字段与技术教程相同；正文要写清环境版本、命令、预期输出和验证方式。
项目复盘模板	项目过程、结果和复盘	`docs/posts/技术笔记/项目记录/10.vitepress-refresh-review.md`	文章字段相同；`categories` 仍只写一级分类 `技术笔记`，`项目记录` 只体现在文件路径和 `permalink` 中。
生活随笔模板	生活经历与个人感受	`docs/posts/生活随笔/10.life-note.md`	文章字段相同；发布前要额外检查隐私、人物授权和图片脱敏。
算法题解模板	一道题的题意、证明、复杂度和代码	`docs/posts/算法竞赛/10.two-sum.md`	文章字段相同；正文需要给出可复现的题意、边界和代码。
建站记录模板	域名、部署、评论、CDN 等操作记录	`docs/posts/技术笔记/10.edgeone-deploy.md`	文章字段相同；正文要写验证结果、回滚方式，并且绝不能记录密钥明文。

除目录页外，六个文章模板共用同一套 frontmatter 字段。模板之间的主要差异是正文结构和目标分类，不是另造一套字段。

路径与公开链接

text

文章文件：docs/posts/<一级分类>/[<子目录>/]<slug>.md
文章 permalink：/posts/<一级分类>/[<子目录>/]<slug>
文章公开地址：https://www.baecon.cn/posts/<一级分类>/[<子目录>/]<slug>

目录页文件：docs/catalog/<目录路径>.md
目录页 path：posts/<目录路径>
目录页 permalink：/catalog/<目录路径>
目录页公开地址：https://www.baecon.cn/catalog/<目录路径>

类型	源文件	关键 frontmatter	permalink	公开地址
一级分类下的文章	`docs/posts/技术笔记/10.vitepress-basics.md`	`categories: [技术笔记]`	`/posts/技术笔记/vitepress-basics`	`https://www.baecon.cn/posts/技术笔记/vitepress-basics`
二级目录下的文章	`docs/posts/技术笔记/项目记录/20.deploy-review.md`	`categories: [技术笔记]`	`/posts/技术笔记/项目记录/deploy-review`	`https://www.baecon.cn/posts/技术笔记/项目记录/deploy-review`
一级分类目录页	`docs/catalog/技术笔记.md`	`path: posts/技术笔记`	`/catalog/技术笔记`	`https://www.baecon.cn/catalog/技术笔记`
二级目录页	`docs/catalog/技术笔记/项目记录.md`	`path: posts/技术笔记/项目记录`	`/catalog/技术笔记/项目记录`	`https://www.baecon.cn/catalog/技术笔记/项目记录`

文件名前的 10.、20. 只用于默认排序，显式 permalink 中使用的是去掉数字前缀后的英文 slug。路径、分类和永久链接要一起检查；二级目录不是第二个 categories。

目录页与文章页的 frontmatter 差异

字段	目录页	文章页	说明
`title`	必填	必填	目录页标题是目录名称；文章标题必须与正文唯一 H1 一致。
`description`	推荐填写	推荐填写	用于 SEO 和摘要。目录页和文章页都应写清楚内容范围。
`desc`	建议省略	建议省略	旧目录页的兼容显示字段，主要供 catalogue 页面使用；不是 SEO 主字段，新页面建议只写 `description`。
`date`	不要使用	首次 Git commit 后自动写入	目录页不是文章；文章不需要手填，文件首次 commit 后启动/构建会自动注入时间。
`updated`	不要使用	可选，通常省略	只覆盖文章的 SEO 修改时间；目录页不使用。
`permalink`	必填，`/catalog/...`	必填，`/posts/...`	两者都必须全站唯一，不能互相混用前缀。
`categories`	不要使用	推荐，只写一级分类	目录页不进入分类归档；文章二级目录不是分类。
`tags`	不要使用	推荐 2–5 个	目录页不进入标签归档。
`coverImg`	可选，建议使用已有图片	可选；通常省略以启用随机封面	文章卡片优先级：显式 `coverImg` → 正文图片随机 → `/home/bg*.webp` 随机；需要固定分享图时才写。目录页仍可写固定封面。
`article`	固定 `false`	推荐显式 `true`	防止目录页被当成文章。
`sidebar`	固定 `false`	推荐显式 `true`	目录页不显示文章侧边栏；文章显示。
`sidebarSort`	不要使用	可选，通常省略	目录页排序由目录结构和文件名前缀决定。
`pagefind-indexed`	固定 `false`	推荐显式 `true`	目录页不参与站内搜索；文章参与搜索。
`comment`	固定 `false`	推荐显式 `true`	目录页不显示评论区；普通文章显示。
`top`	不要使用	可选，默认不写	只有需要进入首页精选文章时才写 `1`。
`sticky`	不要使用	可选，默认不写	置顶排序数字，不是布尔值；目录页不参与文章列表。
`inHomePost`	不要使用	可选，默认 `true`	会影响首页及分类/标签的 HomePost 列表；不是隐私开关。
`inCatalogue`	不要使用	可选，默认 `true`	只影响目录页扫描；`false` 可让文章不出现在目录页，但不是隐私开关。
`titleTag`	不要使用	可选，通常省略	文章标题旁的短标签，不替代分类或标签。
`author`	不要使用	省略	使用站点级作者，不应逐篇覆盖。
`layout`	固定 `page`	省略	目录页必须使用页面布局；文章使用默认文档布局。
`catalogue`	固定 `true`	不要使用	开启 Teek 自动目录扫描。
`path`	必填，`posts/...`	不要使用	推荐统一写成相对 `docs/` 的 `posts/...`；不要写 `docs/posts/...` 或公开 URL。
`pageTitle`	可选，建议 `文档目录`	不要使用	目录列表区域标题，按需修改。

目录页的规则是「少即是安全」：只保留目录页需要的字段。把文章字段复制进去，常常会导致它出现在文章列表、搜索或分类中。

Frontmatter 参考入口

Frontmatter 完整字段手册：全部字段、默认值、推荐值、页面类型和常见错误。
文章 frontmatter 字段总表：title、description、date、permalink、分类、标签、封面和全部文章开关。
目录页 frontmatter 字段表：目录页专用字段和固定值。
VitePress 官方 frontmatter 配置参考：仅用于查阅高级 VitePress 字段；文章模板通常不需要填写这些字段。

发布流程与规则

新增文章与发布流程：从建目录、选模板、填字段到构建部署的完整步骤。
目录页规范：目录页位置、字段和常见问题。
目录结构与 URL 映射：文件系统、目录页、侧边栏、搜索和 URL 的关系。
内容映射关系：目录页与文章进入哪些首页、归档和搜索区域。
写作规范首页：全部写作规则的总入口。

使用模板的步骤

根据内容选择模板；拿不准就使用通用文章模板。
确认目标一级分类目录已经存在，例如 docs/posts/技术笔记/。
如果是新建分类或子目录，先按目录页模板创建 docs/catalog/... 页面。
在 docs/posts/... 下新建 .md 文件，不要在文章目录创建 index.md。
复制模板页代码块中的完整文件内容，不要复制模板页自身的 frontmatter。
按模板的「复制后必须修改」表逐项替换标题、摘要、永久链接、分类、标签和封面；date 不需要手填，文件首次 Git commit 后启动/构建会自动写入。
运行本地开发服务器，检查文章页、目录页、侧边栏、搜索和首页入口；修改 catalogue: true 页面后要重启开发服务器。
发布前运行构建，并按对应模板的检查清单逐项确认。

发布前总检查

文件位置正确：目录页在 docs/catalog/，文章在 docs/posts/，文章目录没有 index.md。
frontmatter 使用两条 --- 完整包裹，YAML 缩进和数组格式正确。
页面只有一个 H1，且 title 与 H1 完全一致。
description 已改成 50–150 个中文字符的摘要。
date 使用 YYYY-MM-DD HH:mm:ss，不是模板占位日期。
permalink 全站唯一，文章以 /posts/ 开头，目录页以 /catalog/ 开头。
categories 只写一级分类，并与文章所在的一级目录一致。
tags 有 2–5 个具体标签，不是整句或分类名。
如写了 coverImg，它指向真实存在的图片；如省略，已确认首页随机封面和分享图回退符合预期。
文章显式保留 article: true、sidebar: true、pagefind-indexed: true、comment: true。
目录页显式保留 article: false、sidebar: false、pagefind-indexed: false、comment: false。
正文图片都有说明性 alt，路径采用 /images/posts/<slug>/<file>.webp。
本地 /posts/...、/catalog/...、侧边栏、搜索和首页卡片均已检查。
构建通过，且没有把 Token、密码、私密截图或个人信息写入文章。