目录页决定读者从哪里进入一组文章。它不是文章，也不是文章目录里的 index.md，而是一个独立放在 docs/catalog/ 下、通过 catalogue: true 和 path 扫描文章目录的页面。

这一篇会把新增、修改、删除目录页的完整链路写清楚，包括 .gitkeep、URL 公式、顶部导航、首页 Banner 卡片和两份 categoryOrder。新增一级分类时，任何一步漏掉都可能出现「文章能打开，但目录入口或导航不出现」的情况。

目录页到底是什么

目录页的最小职责是：

自己提供一个标题、描述和公开 URL。
通过 path 指定要扫描的 docs/posts/ 目录。
由 Teek 的 catalogue 插件自动渲染该目录下的文章列表。
用 sidebar: false、article: false、pagefind-indexed: false、comment: false 避免它被当成普通文章。

它和文章页的区别可以用一句话概括：目录页负责「入口和列表」，文章页负责「正文内容」。

当前仓库中的真实例子：

源文件	`path`	公开 URL
`docs/catalog/技术笔记.md`	`posts/技术笔记`	`/catalog/技术笔记`
`docs/catalog/技术笔记/项目记录.md`	`posts/技术笔记/项目记录`	`/catalog/技术笔记/项目记录`
`docs/catalog/生活随笔.md`	`posts/生活随笔`	`/catalog/生活随笔`
`docs/catalog/算法竞赛.md`	`posts/算法竞赛`	`/catalog/算法竞赛`

对应的文章目录分别是 docs/posts/技术笔记/、docs/posts/技术笔记/项目记录/、docs/posts/生活随笔/、docs/posts/算法竞赛/。catalog 的目录结构与 posts 的目录结构需要镜像，但文件职责完全不同。

为什么不能在 posts 里放 index.md

本站的 sidebar.ts 和 search-manifest.ts 都明确跳过 index.md。如果你把目录内容或文章写在 docs/posts/.../index.md，它不会成为一个正常的文章条目，还可能与目录路由混淆。目录页应该命名为与目录同名的 .md 文件，例如：

text

docs/posts/技术笔记/项目记录/         # 真实文章目录
docs/catalog/技术笔记/项目记录.md     # 对应的目录页文件

不要把 docs/catalog/技术笔记/项目记录.md 改成 docs/catalog/技术笔记/项目记录/index.md。目录页是独立页面，不是文章目录的索引文件。

实际创建的目录页通常只在源码中保留 frontmatter，没有正文和手写 H1；页面中的标题和文章列表由 pageTitle、catalogue 和 path 自动生成。这与写作指南说明页不同：说明页本身需要正文和一个 H1，但目录页源码不需要。

字段作用与推荐值

字段	默认或推荐值	是否必填	作用与说明
`title`	目录的真实名称，例如「项目记录」	必填	页面标题、浏览器标题、目录/导航展示的重要来源。不要随便写成文章标题。
`description`	一句话说明目录内容	强烈建议	用于 SEO description、社交分享和目录说明。
`desc`	可省略；如保留则与 `description` 相同	可选（旧字段）	主要给 Teek 目录组件做显示回退，不是 SEO 主字段；SEO 读取 `description`，首页卡片也不读取它。
`layout`	`page`	必填	固定使用页面布局，不能写成文章默认布局或 `home`。
`catalogue`	`true`	必填	开启目录扫描和列表渲染。缺少它时目录页只是一个空页面。
`path`	`posts/<真实目录路径>`	必填	推荐统一写成相对 `docs/` 的 `posts/...`；插件用 `path.join` 解析，前导 `/` 通常仍指向 docs，但为可读性和跨平台一致性不要依赖它。不能包含 `docs/` 段，也不能写成公开 URL。
`pageTitle`	`文档目录`	推荐	目录列表区域的标题。不同目录可以按需要调整，但要与栏目语义一致。
`permalink`	`/catalog/<目录路径>`	必填	目录页公开 URL。必须显式、唯一、稳定，不能依赖自动生成。
`sidebar`	`false`	必填	目录页不显示文章左侧栏，避免把目录入口当文章。
`article`	`false`	必填	不进入首页、分类、标签、归档、RSS 和 search-manifest；它不直接控制侧边栏或目录扫描，侧边栏看 `sidebar`，目录扫描看 `inCatalogue`。
`pagefind-indexed`	`false`	必填	不进入 Pagefind 搜索。目录页不是文章，不应把目录列表混入全文搜索。
`comment`	`false`	必填	目录页不显示评论。
`coverImg`	`/home/bgXX.webp` 或 `/images/...`	可选但推荐	用于分享封面和页面元数据。可复用 `docs/public/home/` 下的图片。

不要在目录页 frontmatter 里写 categories、tags、date、sticky、top 等文章字段。目录页不是文章，添加它们不会让它变成文章，反而容易误导维护者。

path 和 permalink 的公式

只要记住两个公式：

text

posts 目录：docs/posts/<路径>/
catalog 文件：docs/catalog/<路径>.md
path：posts/<路径>
permalink：/catalog/<路径>

例如：

层级	posts 目录	catalog 文件	path	permalink
一级	`docs/posts/读书笔记/`	`docs/catalog/读书笔记.md`	`posts/读书笔记`	`/catalog/读书笔记`
二级	`docs/posts/技术笔记/项目记录/`	`docs/catalog/技术笔记/项目记录.md`	`posts/技术笔记/项目记录`	`/catalog/技术笔记/项目记录`
三级	`docs/posts/技术笔记/项目记录/2026/`	`docs/catalog/技术笔记/项目记录/2026.md`	`posts/技术笔记/项目记录/2026`	`/catalog/技术笔记/项目记录/2026`

path 中的每一段都必须与真实目录名逐字一致，包括中文、数字和大小写。permalink 使用 /，不带 .html，不带结尾斜杠。Windows 路径 docs\posts\... 只用于 PowerShell 文件操作；frontmatter 内统一写正斜杠 posts/...。

`.gitkeep` 是什么

Git 默认不记录空目录。新建 docs/posts/读书笔记/ 后，如果还没有文章，这个目录不会出现在 git status 中，别人拉取代码后也看不到它。解决办法是在空目录中放一个占位文件：

powershell

New-Item -ItemType File -Force -Path "docs\posts\读书笔记\.gitkeep"

.gitkeep 是社区约定，不是 VitePress 的配置。目录扫描器只处理 .md 文件，会忽略 .gitkeep，所以它不会变成文章。等目录里有了真实文章，可以按团队习惯保留或删除 .gitkeep；如果要保留空目录，就继续保留它。docs/posts/技术笔记/项目记录/、docs/posts/生活随笔/ 和 docs/posts/算法竞赛/ 当前都有这样的空目录占位。

Part A：新增一级分类（10 步）

下面假设新增一级分类「读书笔记」。一级分类会进入顶部导航候选，也需要更新两份 categoryOrder；这是本文最长的一条路径。

1. 创建 posts 文章目录

powershell

New-Item -ItemType Directory -Force -Path "docs\posts\读书笔记"
New-Item -ItemType File -Force -Path "docs\posts\读书笔记\.gitkeep"

如果马上就会添加文章，.gitkeep 可以稍后删除；但先用它保证目录能被 Git 跟踪。不要在这个目录创建 index.md。

2. 创建镜像的 catalog 目录页

一级目录页与 posts 目录同名，但放在 docs/catalog/：

powershell

New-Item -ItemType File -Force -Path "docs\catalog\读书笔记.md"

路径关系是：

text

docs/posts/读书笔记/          → 文章存放位置
docs/catalog/读书笔记.md      → 目录入口页面

3. 填写目录页 frontmatter

打开 docs/catalog/读书笔记.md，写入以下内容。注意 path 不带 docs/，permalink 以 /catalog/ 开头：

yaml

---
title: 读书笔记
description: 读书摘要、章节笔记与个人思考。
layout: page
catalogue: true
path: posts/读书笔记
pageTitle: 文档目录
permalink: /catalog/读书笔记
sidebar: false
article: false
pagefind-indexed: false
comment: false
coverImg: /home/bg11.webp
---

目录页源码后面不要再写 H1 或正文。列表由 catalogue: true 和 path 生成。把标题、description、path、permalink 和封面都改成新分类的真实值，不要保留其他目录的旧值；如果旧页面仍保留 desc，让它与 description 同值。

4. 在 Nav.ts 中加入顶部导航

顶部导航是手工维护的，不会因为新增了 catalog 文件就自动出现。编辑 docs/.vitepress/ConfigHyde/Nav.ts，按现有风格加入：

{
  component: "NavMenuLink",
  props: {
    text: "📚 读书笔记",
    link: "/catalog/读书笔记",
    items: [
      { text: "📚 读书笔记目录", link: "/catalog/读书笔记" },
    ],
  },
},

建议把它放在「文章索引」之前或与你希望的顶部顺序一致的位置。link 和子项 link 都必须与目录页 permalink 完全一致。只改 Nav 不会创建目录页面，只创建目录页面也不会自动出现导航，两者都要做。

5. 同时更新两份 categoryOrder

一级分类的分组顺序在两处代码中各自维护，必须都改：

text

docs/.vitepress/sidebar.ts
docs/.vitepress/search-manifest.ts

两处的 categoryOrder 当前示例为：

const categoryOrder = ["算法竞赛", "技术笔记", "生活随笔"];

新增「读书笔记」后，假设追加到末尾：

const categoryOrder = ["算法竞赛", "技术笔记", "生活随笔", "读书笔记"];

为什么两处都要改？sidebar.ts 用这份数组排列侧边栏的一级分类，search-manifest.ts 用同一份数组决定搜索结果的目录顺序。只改一处会导致侧边栏和搜索列表顺序不一致。数组里写的必须是真实一级目录名，不是显示标题或 URL。

docs/.vitepress/ConfigHyde/Features.ts 是首页 Banner 功能卡片的手写配置，不是自动扫描。只有你确实要把它放到首页功能入口时才加入：

{
  title: "读书笔记",
  details: "读书摘要、章节笔记与个人思考",
  link: "/catalog/读书笔记",
},

当前首页设计以四项卡片为主，新增前先看现有布局，决定是替换、调整还是保留。不要为了一个分类强行堆叠卡片。只创建目录页时，不要误以为它会自动出现在这里。

7. 重启开发服务器

目录页扫描、侧边栏和搜索清单都在 Vite 启动时读取文件系统；修改目录结构后可先保存，若页面不更新就停止并重启：

powershell

pnpm docs:dev

第一次启动前应确认 pnpm install 已经完成。开发服务器默认端口是 5174，以终端实际显示为准。若终端已有 dev 进程，先按 Ctrl+C 停止，再启动，避免误以为热更新已经生效。

8. 验证目录路由以及它不该出现的地方

打开：

text

http://localhost:5174/catalog/读书笔记

检查：

页面能正常打开，标题是「读书笔记」，没有 404。
pageTitle 和文章列表区域正常显示。
列表能看到该目录下的文章，而不是空白或别的分类文章。
目录页没有文章左侧栏。
目录页没有评论区。
在 /search 中搜索目录页标题，不应把目录页当成一篇文章返回。
首页文章流没有把目录页当成文章卡片。

如果还没有任何文章，目录页是空的，无法验证「能看到文章」。先按文章新增完整流程创建至少一篇真实文章，再回到这里检查。可以先创建文件：

powershell

New-Item -ItemType File -Force -Path "docs\posts\读书笔记\01.reading-notes.md"

随后必须填写合法 frontmatter 和正文，并把 permalink 写成 /posts/读书笔记/reading-notes、categories 写成「读书笔记」。空文件不是可发布文章。

文件创建并保存后，停止当前开发服务器（Ctrl+C）并重新启动，再回到目录页验证：

powershell

pnpm docs:dev

目录扫描、侧边栏和搜索清单都在启动阶段读取文件系统；如果只在运行中的 dev 里新建文件，目录页可能暂时仍显示旧列表。

9. 验证文章页、侧边栏和所有汇总页

从目录页点击文章，或直接访问文章 permalink，例如：

text

http://localhost:5174/posts/读书笔记/reading-notes

逐项确认：

文章页显示左侧栏，并且「读书笔记」分组下出现新文章。
文章页显示评论入口。
如果 pagefind-indexed: true，搜索能找到文章正文。
/categories 出现「读书笔记」分类和文章。
/tags 出现文章标签。
/archives 出现文章。
首页文章卡片出现（只要文章 article: true 且未设置 inHomePost: false）。
顶部导航的「读书笔记」链接可点击。
如果更新了 Features.ts，首页 Banner 卡片链接正确。

这里的检查顺序很重要：先确认目录页能扫描文章，再确认文章能进入侧边栏和汇总页。如果目录页有文章但侧边栏没有，先查 sidebar.ts 和文章的 sidebar 字段；如果需要让某篇文章从目录列表隐藏，使用 inCatalogue: false。如果首页/分类/归档没有，才重点查 article: true。

10. 构建、审计、检查 Git、推送并观察 CNB

powershell

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

构建成功后再审计。预览地址默认是 http://localhost:4173/，重点检查目录页、文章、导航、首页 Banner、分类、标签、归档和搜索。

检查 Git 差异，按实际文件精确提交：

powershell

git status
git diff --stat
git add "docs/posts/读书笔记" "docs/catalog/读书笔记.md" "docs/.vitepress/ConfigHyde/Nav.ts" "docs/.vitepress/sidebar.ts" "docs/.vitepress/search-manifest.ts"
git commit -m "docs: add reading notes category"
git push origin main

如果修改了 Features.ts，把它也加入 git add。不要加入 docs/.vitepress/dist/、docs/.vitepress/cache/、docs/public/search-manifest.json 或 stats.html。

推送 main 后 CNB 会执行依赖安装、pnpm docs:build、pnpm docs:audit，并把 docs/.vitepress/dist 部署到 EdgeOne。部署后至少检查：

线上 /catalog/读书笔记 正常。
顶部导航入口正常。
目录页文章链接正常。
首页 Banner（如新增）正常。
侧边栏、分类、标签、归档和搜索正常。
如果要删除旧分类 URL，旧链接按重定向或 404 策略处理。

Part B：新增子目录

子目录不改变一级分类，因此 不需要修改两份 categoryOrder。但仍需要镜像的 catalog 文件，并确保 article 的 categories 仍写一级分类。

假设在「技术笔记」下新增「前端工程」：

1. 创建 posts 子目录

powershell

New-Item -ItemType Directory -Force -Path "docs\posts\技术笔记\前端工程"
New-Item -ItemType File -Force -Path "docs\posts\技术笔记\前端工程\.gitkeep"

同样不要在子目录创建 index.md。

2. 创建镜像目录页

powershell

New-Item -ItemType File -Force -Path "docs\catalog\技术笔记\前端工程.md"

3. 填写子目录页 frontmatter

yaml

---
title: 前端工程
description: 前端开发、构建工具与工程化实践。
layout: page
catalogue: true
path: posts/技术笔记/前端工程
pageTitle: 文档目录
permalink: /catalog/技术笔记/前端工程
sidebar: false
article: false
pagefind-indexed: false
comment: false
coverImg: /home/bg11.webp
---

公式是：

text

path: posts/技术笔记/前端工程
permalink: /catalog/技术笔记/前端工程

不要写成 path: posts/前端工程（漏掉父目录）；path 也不要写成 /posts/技术笔记/前端工程，团队统一使用 posts/技术笔记/前端工程 这种相对写法。

4. 决定是否加 Nav 子菜单

顶部导航是手工维护的。可以在现有「技术笔记」的 items 数组中加入：

{ text: "📁 前端工程", link: "/catalog/技术笔记/前端工程" },

如果不需要从顶部导航直接进入，可以不加；目录页仍然可以通过 URL 或父目录入口访问。子目录不会因为被扫描到就自动加入导航。

5. 首页 Features 仅在需要时添加

如果要把子目录做成首页 Banner 功能卡片，参考 Part A 的结构加入：

{
  title: "前端工程",
  details: "前端开发与工程化实践",
  link: "/catalog/技术笔记/前端工程",
},

不需要就不要改 Features.ts。这里是手工入口，不是目录扫描结果。

6. 子目录文章的字段和 URL

子目录文章的 frontmatter 示例：

yaml

---
title: Vite 构建性能优化
description: 记录 Vite 构建性能分析与优化实践。
permalink: /posts/技术笔记/前端工程/vite-build-performance
categories:
  - 技术笔记
tags:
  - Vite
  - 性能优化
article: true
sidebar: true
pagefind-indexed: true
comment: true
---

permalink 要包含子目录；categories 仍然是一级分类「技术笔记」，不要写「前端工程」。否则分类页会出现一个不该独立存在的新分类。

7. 重启、验证、构建和提交

powershell

pnpm docs:dev

检查 /catalog/技术笔记/前端工程 和文章 URL：

text

http://localhost:5174/catalog/技术笔记/前端工程
http://localhost:5174/posts/技术笔记/前端工程/vite-build-performance

确认目录页有文章、无侧边栏/评论/搜索条目，文章页有侧边栏/评论/搜索，分类仍是「技术笔记」。然后：

powershell

pnpm docs:build
pnpm docs:audit
pnpm docs:preview
git status
git diff --stat
git add "docs/posts/技术笔记/前端工程" "docs/catalog/技术笔记/前端工程.md" "docs/.vitepress/ConfigHyde/Nav.ts"
git commit -m "docs: add frontend engineering section"
git push origin main

如果修改了 Features，再把 docs/.vitepress/ConfigHyde/Features.ts 加入。子目录不需要改 categoryOrder，这是它与一级分类最大的区别。

Part C：修改目录

目录的修改分两类：安全的展示字段修改，以及会改变 URL 的结构修改。先判断是哪一类，再决定需要同步哪些文件。

1. 安全修改：不改 path 和 permalink

下面这些字段通常可以安全修改：

修改项	影响	注意
`title`	目录页标题、浏览器标题、导航显示文字（如果导航手写了相同文字则需同步）	与真实分类含义保持一致
`description`	目录页 SEO 描述；`desc` 仅旧目录显示兼容，如保留需同值	至少修改 `description`
`pageTitle`	目录列表区域标题	只影响页面展示，不影响 URL
`coverImg`	分享或页面封面	路径必须在 `docs/public` 下有对应资源

修改描述后，开发服务器可能热更新；如果目录数据仍显示旧内容，重启：

powershell

pnpm docs:dev

即使 title 改了，docs/posts/... 的真实目录名和 path 仍应保持原值；不要把目录页显示名称和文件系统目录名强行改成不同概念，除非你明确要重命名目录。

2. 修改 path 或 permalink：按结构变更处理

如果目录的公开 URL 要变化，例如：

text

旧：/catalog/技术笔记/项目记录
新：/catalog/技术笔记/项目实践

那么 path、posts 目录、catalog 文件和所有文章 URL 都可能要一起调整。推荐步骤：

规划新目录名，确认 docs/posts/ 和 docs/catalog/ 镜像路径。
用 git mv 移动 posts 子目录和 catalog 文件。
修改目录页的 title、description、path、permalink；如保留旧 desc，同步成相同描述。
逐篇修改该目录下文章的 permalink 前缀。
如果移动的是一级分类，还要修改文章的 categories、Nav.ts、两份 categoryOrder 和 Features.ts。
更新所有手写站内链接。
在托管平台为旧目录 URL 和文章旧 URL 配置重定向。
重启开发服务器，重新构建、审计和预览。

示例：移动子目录：

powershell

git mv "docs/posts/技术笔记/项目记录" "docs/posts/技术笔记/项目实践"
git mv "docs/catalog/技术笔记/项目记录.md" "docs/catalog/技术笔记/项目实践.md"

然后目录页改为：

yaml

path: posts/技术笔记/项目实践
permalink: /catalog/技术笔记/项目实践

子目录移动时，文章 categories 仍是「技术笔记」，但 permalink 要从：

yaml

permalink: /posts/技术笔记/项目记录/example

改成：

yaml

permalink: /posts/技术笔记/项目实践/example

只改目录页的 path/permalink 而不管文章 permalink，会出现目录页指向新目录、文章仍停在旧 URL 的混搭状态，虽然可能还能访问，但后续维护和搜索归档会出现不一致。无论改的是子目录还是一级分类，只要 Nav.ts 或 Features.ts 里写有旧目录链接，都必须同步改成新地址。两份 categoryOrder 只在顶级分类发生变化时才需要改；子目录改名不要误加分类名。文章 categories 则在跨一级分类移动时必须更新，在同一一级分类内移动子目录时保持不变。

3. 一级分类的额外同步

如果一级分类名称变化，例如从「读书笔记」改成「阅读笔记」，除了 posts 和 catalog 路径，还要：

修改所有文章的 categories，让分类汇总正确；
修改 Nav.ts 的导航文字和链接；
修改 sidebar.ts 与 search-manifest.ts 的 categoryOrder；
如果首页 Banner 有卡片，修改 Features.ts 的 title 和 link；
检查所有手写旧链接；
在托管平台配置旧目录和旧文章 URL 的重定向。

如果只是改一级分类的显示顺序，不需要移动文件，只需调整两份 categoryOrder；如果还要改顶部导航顺序，再调整 Nav.ts。

4. 调整目录内文章顺序

文章的目录顺序有两个常用办法：

方法	怎么写	影响
文件编号前缀	`01.article.md`、`02.article.md`	扫描器读取数字前缀，影响侧边栏/搜索清单中的文章顺序；排版直观
`sidebarSort`	文章 frontmatter `sidebarSort: 1`	覆盖文件编号，数字越小越靠前，只影响文章顺序

如果只是重命名文件编号，公开 permalink 不变就没有 URL 风险，但要用 git mv：

powershell

git mv "docs/posts/技术笔记/项目记录/02.article.md" "docs/posts/技术笔记/项目记录/01.article.md"

如果目录内还有子目录，目录的排序使用目录名的数字前缀；此时 path 必须与真实目录名完全一致。新手更推荐目录名保持稳定、文章使用编号，避免 path 与真实文件夹名不同步。

5. 修改后的检查清单

修改 path、permalink、目录名或文章文件位置后，先停止并重启开发服务器，再做下面的检查：

powershell

pnpm docs:dev

目录页 path 与真实 posts 目录完全一致。
目录页 permalink 以 /catalog/ 开头且唯一。
目录中的文章 permalink 前缀与新目录一致。
子目录文章的 categories 仍是一级分类，没有误建新分类。
一级分类变更时，Nav、Features、两份 categoryOrder 全部同步。
旧目录和旧文章链接已评估重定向。
目录页无侧边栏、无评论、无 Pagefind 索引。
文章、侧边栏、分类、标签、归档和搜索都重新验证。
构建、审计和预览全部通过。

修改完成后重新运行：

powershell

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

如果只改标题或描述，可以只做开发检查和构建；如果改 path、permalink 或目录结构，必须完整做一遍检查并考虑重定向。

Part D：删除目录

删除目录页不只是删一个 .md。你要先处理目录里的文章、图片、导航、首页卡片、分类顺序和旧 URL，否则很容易留下死链或配置指向不存在的路径。

1. 先评估并记录

先回答：

只是删除目录入口，还是连文章也删除？
文章是否要移动到其他目录？如果移动，新的 permalink 和 categories 是什么？
目录页 URL 是否已经公开？需要 301 重定向吗？
目录里是否有共享图片、被其他页面引用的资源？
这是子目录还是顶级分类？顶级分类还要处理 categoryOrder。

把旧目录 URL、旧文章 URL 和旧导航文字记录下来，后面验收时要用。

2. 搜索所有引用

powershell

Get-ChildItem docs -Recurse -File -Include *.md,*.ts | Select-String -Pattern "/catalog/技术笔记/前端工程"
Get-ChildItem docs -Recurse -File -Include *.md,*.ts | Select-String -Pattern "/posts/技术笔记/前端工程/"

同时搜索目录标题和图片路径。重点检查 Nav.ts、Features.ts、其他文章的正文、写作指南里的示例和目录页正文。自动生成的目录列表不需要手删，手写链接必须删。

3. 先移动或删除目录里的文章

如果文章要继续保留，先用 git mv 移到已有目录，并更新 permalink、categories（跨一级分类时）和图片引用：

powershell

git mv "docs/posts/技术笔记/前端工程/01.vite-build.md" "docs/posts/技术笔记/01.vite-build.md"

如果文章确实不需要了，确认没有历史价值或保留需求后再删除：

powershell

Remove-Item -LiteralPath "docs\posts\技术笔记\前端工程\01.vite-build.md"
Remove-Item -LiteralPath "docs\posts\技术笔记\前端工程\02.performance.md"

不要先删除整个 posts 目录再回头找文章。先逐篇决定去留，才能知道哪些 permalink、图片和链接需要处理。

删除 catalog 目录页文件：

powershell

if (Test-Path "docs\catalog\技术笔记\前端工程.md") {
  Remove-Item -LiteralPath "docs\catalog\技术笔记\前端工程.md"
}

如果 catalog 子目录已经空了，可以删除目录（目录不存在时跳过）：

powershell

if (Test-Path "docs\catalog\技术笔记\前端工程") {
  Remove-Item -LiteralPath "docs\catalog\技术笔记\前端工程" -Recurse
}

确认 posts 目录中的文章都已移动或删除后，删除空目录：

powershell

if (Test-Path "docs\posts\技术笔记\前端工程") {
  Remove-Item -LiteralPath "docs\posts\技术笔记\前端工程" -Recurse
}

图片目录只有在确认没有共享引用后删除：

powershell

if (Test-Path "docs\public\images\posts\frontend-engineering") {
  Remove-Item -LiteralPath "docs\public\images\posts\frontend-engineering" -Recurse
}

删除前可以先加 -WhatIf 查看将被删除的路径，确认后再执行真正删除。Remove-Item -Recurse 不会进入回收站。

5. 清理 Nav、Features 和 categoryOrder

从 docs/.vitepress/ConfigHyde/Nav.ts 删除该目录的菜单对象或子菜单项。
从 docs/.vitepress/ConfigHyde/Features.ts 删除指向旧目录的首页卡片。
如果删除的是顶级分类，从 docs/.vitepress/sidebar.ts 和 docs/.vitepress/search-manifest.ts 两份 categoryOrder 中删除分类名。只删一处会导致侧边栏和搜索顺序不一致。
如果删除的是子目录，通常不需要改 categoryOrder，但要检查 Nav 子菜单和 Features 是否有它的入口。
清理所有手写链接和旧 URL 引用。

如果目录中仍有其他文章保留，不要删除整个目录页；应该保留目录页并只删除相关文章入口。只有目录整体取消时，才删除目录页。

6. 重启开发服务器并检查

powershell

pnpm docs:dev

检查：

旧目录 /catalog/技术笔记/前端工程 已不存在或按预期 404。
其他目录页仍正常。
侧边栏不再出现被删目录。
首页 Banner 不再有旧卡片。
顶部导航没有旧链接。
移走的文章在新目录和新 URL 正常。
删除的文章不再被首页、分类、标签、归档或搜索显示。
图片没有被误删导致其他文章 404。

7. 构建、审计和预览

powershell

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

构建并审计后，检查 sitemap 是否还包含旧目录 URL、RSS 是否还有旧文章、Pagefind 是否还能搜到已删除内容。若旧内容仍出现，检查是否部署的是旧 dist、是否还有另一个同名源文件、是否有其他路由或手写页面仍指向旧 URL。

8. 检查 Git、提交并推送

powershell

git status
git diff --stat
git add "docs/posts/技术笔记" "docs/catalog/技术笔记" "docs/.vitepress/ConfigHyde/Nav.ts" "docs/.vitepress/ConfigHyde/Features.ts" "docs/.vitepress/sidebar.ts" "docs/.vitepress/search-manifest.ts"
git commit -m "docs: remove frontend engineering section"
git push origin main

git add 对已删除文件会登记删除；如果某个文件没有修改，git add 不会凭空创建变更。按实际改动精简命令，避免把不相关文件加入提交。

9. 部署后验收和旧 URL 处理

CNB 会依次执行依赖安装、构建、审计和 EdgeOne 部署。部署后检查：

旧目录 URL：按策略返回 301 或 404。
旧文章 URL：如果文章被移动，配置了重定向就应跳转到新地址；否则会 404。
新目录、新文章、导航和首页卡片正常。
分类、标签、归档和搜索不再混入旧内容。
sitemap 和 RSS 中没有意外残留。

静态站不会自动生成重定向。若旧 URL 需要继续对外服务，必须在托管平台配置；删除文件本身不能完成 301。只删除源文件而不处理外部链接，是目录删除中最常见的遗留问题。

完整检查清单

新增一级分类

docs/posts/<分类>/ 已创建，空目录有 .gitkeep。
docs/catalog/<分类>.md 已创建，路径与 posts 镜像。
目录页 layout: page、catalogue: true。
path 统一写成 posts/<分类> 相对路径，没有 docs/ 段、没有反斜杠。
permalink 是 /catalog/<分类>，显式且唯一。
title、description、pageTitle 已替换为新分类；如使用 coverImg，路径真实存在；如保留旧 desc，与 description 同值。
sidebar: false、article: false、pagefind-indexed: false、comment: false。
目录页源码没有额外正文或第二个 H1。
Nav.ts 已加入顶部导航，链接与 permalink 一致。
sidebar.ts 和 search-manifest.ts 的 categoryOrder 都已加入分类。
需要首页卡片时才改 Features.ts，并确认链接正确。
该分类下的文章 categories 与一级分类一致。
文章 permalink 使用 /posts/<分类>/...。
开发环境目录页、文章、侧边栏、首页、分类、标签、归档、搜索、评论和封面全部检查。
构建、审计、预览通过，Git 只包含预期源文件，推送后 CNB 部署成功。

新增子目录

docs/posts/<一级分类>/<子目录>/ 已创建，空目录有 .gitkeep。
docs/catalog/<一级分类>/<子目录>.md 已创建。
path 写 posts/<一级分类>/<子目录>。
permalink 写 /catalog/<一级分类>/<子目录>。
子目录文章 permalink 包含子目录。
子目录文章 categories 仍写一级分类。
需要时更新 Nav.ts 子菜单和 Features.ts；不需要时保持不动。
没有修改 categoryOrder，除非同时新增了顶级分类。
开发、构建、审计和预览都通过。
旧子目录 URL 若改变，已配置重定向并更新手写链接。

修改目录

只改标题、描述、pageTitle、封面时，确认页面展示和 SEO 更新。
如保留旧 desc，其内容与 description 一致。
改 path/permalink 时，真实 posts 目录、catalog 文件和 frontmatter 三者一致。
该目录下所有文章 permalink 已更新。
跨一级分类移动时，文章 categories 已更新。
Nav、Features 和手写链接中的旧地址已更新。
顶级分类顺序变化时，两份 categoryOrder 都已更新。
旧目录/文章 URL 已评估重定向。
目录页仍有正确的四个关闭开关。
构建、审计和预览通过。

删除目录

已决定每篇文章是移动还是删除。
所有文章、目录页、图片和手写链接引用都已搜索。
需要保留的文章已经移动并更新 permalink/categories。
catalog 目录页已删除，空的 catalog 子目录已处理。
posts 空目录已删除，或按计划用 .gitkeep 保留。
只被该目录使用的图片已删除；共享图片仍保留。
Nav.ts 和 Features.ts 的旧入口已删除。
顶级分类已从两份 categoryOrder 删除。
开发服务器没有旧目录/旧文章入口。
构建、审计和预览通过。
旧 URL 已配置重定向或明确接受 404。
CNB 部署后已做线上验收。

常见问题、原因与修复

问题	常见原因	修复方式
`/catalog/新分类` 404	catalog 文件没创建、文件名与 URL 不一致、dev 未重启	检查 `docs/catalog/...md`、`permalink`，重启 `pnpm docs:dev`
目录页打开但列表为空	`path` 指向不存在的目录、文章 `inCatalogue: false`、目录还在扫描缓存中	让 path 精确匹配真实目录；确认文章未被 `inCatalogue: false` 排除；重启开发服务器
目录页出现左侧栏	缺少 `layout: page`、`sidebar: false`，或误用了文章布局	补齐推荐 frontmatter，重启检查
目录页出现评论	`comment` 没写或写成 `true`	改为 `comment: false`
目录页能被 Pagefind 搜到	`pagefind-indexed` 没写或写成 `true`	改为 `false`，重新构建后验证
目录页进了首页文章流	`article` 没写或写成 `true`	改为 `article: false`
新增分类后侧边栏顺序不对	只改了 `sidebar.ts`，或只改了 `search-manifest.ts`	两处 `categoryOrder` 同时修改并重启
顶部导航没有新入口	误以为 catalog 会自动注册导航	手工编辑 `Nav.ts`
首页 Banner 没有新卡片	误以为 Features 会自动扫描目录	需要时手工编辑 `Features.ts`
`path` 写了却找不到目录	写成 `docs/posts/...`、反斜杠路径、错误的目录名，或目录名有前后空格	改为 `posts/...`，逐字核对真实目录名；前导 `/` 是风格问题，不是主要失败原因
空 posts 目录没有被 Git 跟踪	Git 不记录空目录	放一个 `.gitkeep`；它是占位文件，不是文章
目录改名后文章 URL 还是旧的	只改了 catalog 的 path/permalink	逐篇更新文章 permalink，评估旧 URL 重定向
子目录文章让分类页多出「前端工程」	把子目录名写进了 categories	categories 只写一级分类，如「技术笔记」
删除目录后导航仍指向旧地址	只删了文件，没改 Nav/Features	搜索旧链接并删除入口，构建后验收
删除文章后搜索仍能搜到	还在使用旧构建产物或没重新构建	重新 `pnpm docs:build`，清空浏览器缓存后预览验证
删除后旧 URL 直接 404	静态站没有自动重定向	在托管平台配置 301，或明确接受 404
审计报 H1 数量错误	在目录页源码里手写了 H1，或文章正文有多个 H1	目录页只保留 frontmatter；文章只保留一个 H1
图片或封面 404	图片没放 public、引用路径多了 public、大小写不一致	放到 `docs/public/images/posts/...`，引用 `/images/...`

目录结构不是「看起来差不多」就行，而是要在 path、permalink、真实文件夹、Nav、Features 和两份 categoryOrder 之间保持一致。按本文流程先判断层级，再逐项修改，最后用开发预览和生产预览双重验收，就能避免大多数看不见的联动错误。

目录页与目录新增、修改、删除完整流程 ​

目录页到底是什么 ​

为什么不能在 posts 里放 index.md ​

推荐的标准 frontmatter ​

字段作用与推荐值 ​

path 和 permalink 的公式 ​

.gitkeep 是什么 ​

Part A：新增一级分类（10 步） ​

1. 创建 posts 文章目录 ​

2. 创建镜像的 catalog 目录页 ​

3. 填写目录页 frontmatter ​

4. 在 Nav.ts 中加入顶部导航 ​

5. 同时更新两份 categoryOrder ​

6. 需要首页 Banner 卡片时才更新 Features.ts ​

7. 重启开发服务器 ​

8. 验证目录路由以及它不该出现的地方 ​

9. 验证文章页、侧边栏和所有汇总页 ​

10. 构建、审计、检查 Git、推送并观察 CNB ​

Part B：新增子目录 ​

1. 创建 posts 子目录 ​

2. 创建镜像目录页 ​

3. 填写子目录页 frontmatter ​

4. 决定是否加 Nav 子菜单 ​

5. 首页 Features 仅在需要时添加 ​

6. 子目录文章的字段和 URL ​

7. 重启、验证、构建和提交 ​

Part C：修改目录 ​

1. 安全修改：不改 path 和 permalink ​

2. 修改 path 或 permalink：按结构变更处理 ​

3. 一级分类的额外同步 ​

4. 调整目录内文章顺序 ​

5. 修改后的检查清单 ​

Part D：删除目录 ​

1. 先评估并记录 ​

2. 搜索所有引用 ​

3. 先移动或删除目录里的文章 ​

4. 删除目录页、posts 目录和图片 ​

5. 清理 Nav、Features 和 categoryOrder ​

6. 重启开发服务器并检查 ​

7. 构建、审计和预览 ​

8. 检查 Git、提交并推送 ​

9. 部署后验收和旧 URL 处理 ​

完整检查清单 ​

新增一级分类 ​

新增子目录 ​

修改目录 ​

删除目录 ​

常见问题、原因与修复 ​

目录页与目录新增、修改、删除完整流程

目录页到底是什么

为什么不能在 posts 里放 index.md

推荐的标准 frontmatter

字段作用与推荐值

path 和 permalink 的公式

`.gitkeep` 是什么

Part A：新增一级分类（10 步）

1. 创建 posts 文章目录

2. 创建镜像的 catalog 目录页

3. 填写目录页 frontmatter

4. 在 Nav.ts 中加入顶部导航

5. 同时更新两份 categoryOrder

6. 需要首页 Banner 卡片时才更新 Features.ts

7. 重启开发服务器

8. 验证目录路由以及它不该出现的地方

9. 验证文章页、侧边栏和所有汇总页

10. 构建、审计、检查 Git、推送并观察 CNB

Part B：新增子目录

1. 创建 posts 子目录

2. 创建镜像目录页

3. 填写子目录页 frontmatter

4. 决定是否加 Nav 子菜单

5. 首页 Features 仅在需要时添加

6. 子目录文章的字段和 URL

7. 重启、验证、构建和提交

Part C：修改目录

1. 安全修改：不改 path 和 permalink

2. 修改 path 或 permalink：按结构变更处理

3. 一级分类的额外同步

4. 调整目录内文章顺序

5. 修改后的检查清单

Part D：删除目录

1. 先评估并记录

2. 搜索所有引用

3. 先移动或删除目录里的文章

4. 删除目录页、posts 目录和图片

5. 清理 Nav、Features 和 categoryOrder

6. 重启开发服务器并检查

7. 构建、审计和预览

8. 检查 Git、提交并推送

9. 部署后验收和旧 URL 处理

完整检查清单

新增一级分类

新增子目录

修改目录

删除目录

常见问题、原因与修复