写作指南

欢迎来到 Baecon's Blog 的写作指南。如果你已经会用 Markdown 写标题、列表、链接和代码块，但还不知道这个博客里「文件应该放哪里、frontmatter 要写什么、为什么文章没有出现在首页」，请从这里开始。

本站不是普通 Markdown 笔记本：文章文件会经过 VitePress、Teek 主题、Pagefind 搜索、RSS、sitemap 和 CNB 构建，再部署到 EdgeOne。任何一个路径或开关写错，页面都可能「文件存在但入口不见了」。这套指南的目标不是让你背配置，而是让你理解每一步为什么这样做，并能独立完成新增、修改、删除和发布。

这套指南适合谁

• 会基本 Markdown，但没有写过静态博客的新手。
• 接手 E:\vitepress-teek-my-blog\teek-hyde 后，需要安全新增文章的人。
• 需要新增、修改或删除一个目录入口的人。
• 已经改过文件，却发现首页、侧边栏、目录页或搜索结果不一致，需要排查的人。

你不需要先学会 Vue 或 TypeScript。日常写文章主要编辑 docs/posts/、docs/catalog/、docs/public/images/posts/ 这几个位置；只有新增一级分类或调整顶部导航时，才需要修改少量 .ts 配置。

读完以后你会掌握什么

1. 分清源文件、构建产物和自动生成文件，知道哪些能改、哪些绝对不能手改。
2. 分清「目录页」和「文章页」，知道为什么它们分别在 docs/catalog/ 与 docs/posts/。
3. 独立写好一篇文章的 frontmatter，并理解每个字段会让哪些页面发生变化。
4. 安全处理新增、编辑、删除、重命名和移动，避免无意中制造死链。
5. 在本地完成开发检查、生产构建、SEO 审计和构建产物预览。
6. 通过 Git 提交并由 CNB 自动构建、审计、部署，最后做线上验收。

推荐阅读顺序

建议按下面的顺序读，不要跳着只复制模板。前四篇建立规则，后三篇是操作和排障。

1. 项目结构、文件位置与 URL 规则：先认识仓库，知道源文件在哪里、URL 由什么决定。
2. Markdown 基础：复习本站会用到、容易写错的 Markdown 写法。
3. Frontmatter 字段手册：逐个理解文章和目录页的字段。
4. 内容模板：根据文章类型选择可复制模板，避免从空白文件开始。
5. 文章新增、修改、删除完整流程：按 20 个步骤发布第一篇文章。
6. 目录页与目录新增、修改、删除完整流程：当你要增加一级分类或子目录时使用。
7. 构建、发布与故障排查：学习构建、CNB 部署、验收和常见问题处理。

如果你是第一次操作，建议至少先读完第 1、3、5 篇，再动手创建文章。

先分清：目录页和文章页

这是全站最重要的概念。两者都是 Markdown 文件，但用途、frontmatter 和生成结果完全不同。

对比项	目录页（catalog page）	文章页（article page）
源文件位置	docs/catalog/...	docs/posts/...
典型 URL	/catalog/技术笔记	/posts/技术笔记/项目复盘模板
主要字段	layout: page、catalogue: true、path	普通文章 frontmatter
页面内容	通常只写 frontmatter，由目录插件根据 path 生成文章列表	自己写 H1 和完整正文
首页文章列表	不进入	article: true 时进入
左侧栏	sidebar: false	sidebar: true
Pagefind 搜索	pagefind-indexed: false	pagefind-indexed: true
评论	comment: false	comment: true
分类、标签、归档	不参与	article: true 时参与
顶部导航	需要手动在 Nav.ts 中添加入口	通常由目录页和侧边栏进入，不需要单独加导航

注意：实际创建的目录页一般不需要正文，也不写 H1，因为列表由 catalogue 插件生成；而你现在读的写作指南说明页本身是普通说明页，所以按照本仓库的 SEO 审计要求保留一个 H1。不要把「目录页不写 H1」误解成「所有说明页都不写 H1」。

十二条黄金规则

1. 文章目录里绝不放 index.md。 本站的侧边栏扫描器和搜索清单都明确跳过 index.md。文章使用 NN.english-slug.md 这样的具名文件，目录入口使用 docs/catalog/ 下的对应文件。
2. 每篇文章都必须写显式、唯一、稳定的 permalink。 它是真正的公开 URL。当前自动 frontmatter 配置会跳过已有 frontmatter 的文章，不能依赖自动补全；必须显式写稳定地址。
3. 一篇页面只能有一个 H1，且推荐与 frontmatter 的 title 一致。 标题承担页面层级、SEO 和目录识别，重复 H1 会让审计失败。
4. 日期统一写成 YYYY-MM-DD HH:mm:ss。 例如 2026-11-07 12:00:00。不要写 2026/11/07、只写月日，或把日期随便留空。
5. 文章开关要成组正确。 正式文章通常写 article: true、sidebar: true、pagefind-indexed: true、comment: true；目录页和写作规范页则全部设为 false。
6. 不要手改生成文件。 docs/.vitepress/dist/、docs/.vitepress/cache/、docs/public/search-manifest.json、stats.html 都是构建或扫描产物，改了也会被覆盖，而且可能污染本地状态。
7. 图片放对位置并写 alt。 正文图片放在 docs/public/images/posts/<slug>/，引用 /images/posts/<slug>/<file>.webp；coverImg 可选：需要固定首页卡片或分享图时写站内绝对路径；不写时首页卡片会随机使用正文图片或 /home/bg*.webp。所有正文图片都必须有说明性 alt。
8. 发布后不要随意改 permalink。 URL 一旦公开，就把它当成承诺。必须修改时，要同时修正所有站内链接，并在托管平台配置重定向；静态站不会自动帮你保留旧地址。
9. 文件名也不要频繁改。 显式 permalink 可以让 URL 暂时不变，但文件重命名会影响扫描顺序、图片目录对照和 Git 历史。确需改名时用 git mv 并完整检查。
10. 新增一级分类不是「建个文件夹」就结束。 还要创建镜像目录页、更新 Nav.ts、同时更新 sidebar.ts 和 search-manifest.ts 的 categoryOrder；需要首页 Banner 卡片时再改 Features.ts。
11. 推送前必须本地构建和审计。 至少执行 pnpm docs:build 与 pnpm docs:audit，再用 pnpm docs:preview 检查生产产物。只刷新开发服务器不足以发现所有构建问题。
12. 提交前看 git status，推送后看 CNB。 只提交自己这次要改的源文件，不要提交生成目录；推送 main 后等 CNB 的安装、构建、审计和 EdgeOne 部署完成，再到线上做一次冒烟检查。

10 步发布第一篇文章

下面是最短可执行路径。每一步为什么重要都写出来了；完整细节和 20 步版本在文章新增、修改、删除完整流程。

1. 同步主分支。 先确认自己在 main，拉取最新代码，避免基于旧版本写文章。

git switch main
git pull --rebase origin main

2. 进入仓库根目录。 所有 pnpm 命令都必须在包含 package.json 的目录执行。

cd "E:\vitepress-teek-my-blog\teek-hyde"

3. 首次使用安装依赖。 依赖已在 node_modules 时可跳过，但不确定时先安装最稳妥。

pnpm install

4. 新建文章图片目录。 即使暂时没有图片，也先建立与文章 slug 对应的目录，后续路径不易混乱。

New-Item -ItemType Directory -Force -Path "docs\public\images\posts\vitepress-deploy-guide"

5. 在已有分类下创建文章文件。 文件名用两位编号加英文 slug；编号用于扫描排序，slug 便于识别。

New-Item -ItemType File -Force -Path "docs\posts\技术笔记\项目记录\01.vitepress-deploy-guide.md"

6. 复制模板并填写 frontmatter。 从通用文章模板或项目复盘模板复制代码块内容，然后修改标题、描述、日期、permalink、分类、标签和封面。不要直接复制模板说明页的 frontmatter。
7. 写 H1 和正文。 H1 与 title 使用同一个中文标题；二级标题从 ## 开始。图片使用站内绝对路径，例如 /images/posts/vitepress-deploy-guide/build-success.webp，并写清楚 alt。
8. 启动开发服务器并检查所有入口。 先看终端有没有 YAML 或 Markdown 编译错误，再打开文章、首页、目录页、侧边栏、分类、标签、归档、搜索、评论和封面；链接与图片是否可用需要逐项点击检查。

pnpm docs:dev

开发服务器默认端口是 5174，以终端实际打印的地址为准。文章预期地址是 http://localhost:5174/posts/技术笔记/项目记录/vitepress-deploy-guide。

9. 构建、审计并预览生产产物。 构建成功后再审计；审计读取的是 docs/.vitepress/dist/，没有构建产物就无法可靠检查。预览确认无误后才推送。

pnpm docs:build
pnpm docs:audit
pnpm docs:preview

10. 检查 Git 变更并提交，然后推送、观察 CNB、做线上验收。 只添加文章和图片，不添加 dist、cache、search-manifest.json 或 stats.html。

git status
git diff --stat
git add "docs/posts/技术笔记/项目记录/01.vitepress-deploy-guide.md" "docs/public/images/posts/vitepress-deploy-guide"
git commit -m "docs: add vitepress deploy guide"
git push origin main

推送后 CNB 会执行 pnpm install --frozen-lockfile、pnpm docs:build、pnpm docs:audit，再把 docs/.vitepress/dist 部署到 EdgeOne。部署完成后至少检查线上文章 URL、首页卡片、目录页、侧边栏、分类、标签、归档、搜索、RSS 和封面。

应该使用哪个模板

模板页本身是「说明页」，复制的是其中的代码块。新建文章时按下表选择，不要把所有模板字段混在一起。

模板	适合的内容	复制到
通用文章模板	没有特殊结构的普通文章	docs/posts/<一级分类>/NN.slug.md
技术教程模板	有前置条件、步骤和验证结果的技术教程	docs/posts/技术笔记/NN.slug.md 或子目录
项目复盘模板	项目背景、方案、实施、结果和复盘	docs/posts/技术笔记/项目记录/NN.slug.md
生活随笔模板	生活经历、感受和日常思考	docs/posts/生活随笔/NN.slug.md
算法题解模板	题意、思路、复杂度、代码和易错点	docs/posts/算法竞赛/NN.slug.md
建站记录模板	域名、部署、评论、CDN 和博客配置记录	docs/posts/技术笔记/ 或 docs/posts/技术笔记/项目记录/
目录页模板	新建一个目录入口页面	docs/catalog/<与文章目录镜像的路径>.md

如果你只是往已有目录加一篇文章，不需要改 Nav.ts、Features.ts 或 categoryOrder。如果你要新增一级分类，请直接阅读目录页完整流程，那里列出了必须同步的全部位置。

遇到问题先查哪里

• 文章 404：先核对 permalink、文件是否在 docs/posts/、开发服务器是否重启，以及 URL 是否误加了 .html。
• 首页/分类/标签不出现：检查 article: true、inHomePost 是否被设为 false、date 是否合法。
• 侧边栏不出现：检查 sidebar: false、是否误用了 index.md；article: false 不会直接移除侧栏。
• 目录页没有文章：检查 catalogue: true 和 path 是否精确指向 docs/posts/ 下真实存在的目录。
• 搜索不到：检查 pagefind-indexed: true，并优先用生产构建后的预览验证。
• 构建或审计失败：查看终端第一条真正的错误信息，不要只盯着最后一行。

完整的「症状—原因—处理」矩阵见构建、发布与故障排查。第一次写完后，建议把这套指南第 5 篇的检查表完整走一遍，再开始下一篇。