目录页模板

目录页是 Teek 的 catalogue 页面：它扫描 docs/posts/ 下的一个目录，自动列出其中的文章和子目录。目录页不是文章，也不是靠手写链接维护的普通页面。

用途

• 为一个一级分类提供自动文章入口，例如「技术笔记」。
• 为一个二级分组提供自动文章入口，例如「技术笔记 / 项目记录」。
• 让新增文章自动出现在目录页，而不必每次手动修改列表。
• 让目录结构与 docs/posts/ 的真实文件结构保持一致。

放在哪里

目录页统一放在 docs/catalog/，并与 docs/posts/ 中的文章目录保持同名层级。

层级	目录页源文件	path	permalink	公开地址
一级分类	docs/catalog/技术笔记.md	posts/技术笔记	/catalog/技术笔记	https://www.baecon.cn/catalog/技术笔记
二级目录	docs/catalog/技术笔记/项目记录.md	posts/技术笔记/项目记录	/catalog/技术笔记/项目记录	https://www.baecon.cn/catalog/技术笔记/项目记录

对应的文章目录分别是 docs/posts/技术笔记/ 和 docs/posts/技术笔记/项目记录/。文章目录里只放文章，不要创建 index.md。

什么时候使用

• 新建了一个一级分类，需要一个自动文章目录。
• 在一个一级分类下新建了二级分组，需要单独的目录入口。
• 想按真实文件结构展示一个目录下的文章、子目录和标题。
• 文章会持续增加，手动维护链接容易漏项。

什么时候不要使用

• 要写一篇真正的文章、教程、复盘、随笔或题解。请使用对应的文章模板。
• 要写一段需要自由排版的目录说明或自定义卡片。目录页只保留 frontmatter，页面主体由插件生成，不适合写长正文。
• 要访问全站的分类、标签或归档页。这些页面由现有功能页提供，不要重复创建。
• 不要为了占位而在 docs/posts/ 下创建 index.md；文章目录不创建索引文件。

新增一级分类时，目录页只是其中一步。根据仓库当前流程，还要同步检查 docs/.vitepress/ConfigHyde/Nav.ts、docs/.vitepress/sidebar.ts 和 docs/.vitepress/search-manifest.ts 中的分类顺序或导航入口。

完整文件模板

下面代码块中的整个文件只有 frontmatter，没有正文。复制后按下一节修改字段。

---
title: 技术笔记
description: 收录技术学习、工程实践、项目开发、部署运维和问题复盘等文章，持续记录可复用的方法、工具、流程与实践经验，方便读者按主题查阅。
layout: page
catalogue: true
path: posts/技术笔记
pageTitle: 文档目录
permalink: /catalog/技术笔记
sidebar: false
article: false
pagefind-indexed: false
comment: false
coverImg: /home/bg11.webp
---

完整目录页 frontmatter 字段表

字段	类型	省略时默认	推荐值	级别	完整说明
title	string	无可靠默认	与目录名称一致，例如 技术笔记	必填	目录页标题，用于导航、浏览器标题和页面展示。应与目标文章目录的名称和用途一致。
description	string	SEO 会回退到站点描述	50–150 个中文字符，概括该目录收录什么	推荐	目录页的 SEO 描述和摘要。应说明目录范围，例如技术学习、项目实践和复盘记录。
desc	string	未设置	省略	可选（旧字段）	主要给 Teek 目录组件做显示回退；不是 SEO 主字段，首页卡片也不读取它。新目录页建议只用 description；如保留 desc，需与 description 同值。
layout	string	VitePress 默认文档布局	固定为 page	必填（固定）	目录页必须使用 Teek 的页面布局，才能渲染自动目录。不要删除，也不要改成文章默认布局。
catalogue	boolean	不启用目录扫描	固定为 true	必填（固定）	告诉 Teek 这是一张目录页，需要读取 path 指向的文章目录并生成目录列表。
path	string	无，未设置则不扫描	posts/<目录路径>，例如 posts/技术笔记	必填	要扫描的文章目录。推荐统一写成相对 docs/ 的 posts/...；插件用 path.join 解析，但不建议依赖前导 /。不能写 docs/ 段，也不能指向 docs/catalog/。
pageTitle	string	主题默认目录标题	文档目录，或更具体的 项目记录	可选	目录列表中显示的标题文案。它和页面 title 不是同一个值：title 是页面名称，pageTitle 是列表区域标题。
permalink	string	会按文件路径生成路由，但本项目不依赖默认值	全站唯一且以 /catalog/ 开头，例如 /catalog/技术笔记	必填	目录页的公开 URL。必须与 path 的目录层级对应，不能使用 /posts/ 开头，不能包含 .md，也不能与其他目录页重复。
sidebar	boolean	VitePress 默认为 true	固定为 false	必填（固定）	目录页不是文章，不应显示文章左侧侧边栏。若出现侧边栏，通常是错用了文章模板。
article	boolean	/posts/ 外通常不算文章	固定为 false	必填（固定）	防止目录页进入首页文章卡片、归档、分类和标签等文章区域。
pagefind-indexed	boolean	true	固定为 false	必填（固定）	阻止 Pagefind 把目录页收进站内搜索。目录内容会随文章变化，搜索文章正文即可，不应重复索引目录页。
comment	boolean	未写 false 时按开启处理	固定为 false	必填（固定）	目录页不提供评论区，避免读者在自动生成的目录页下讨论而脱离具体文章。
coverImg	string	不保证有自定义封面	使用仓库已有图片，如 /home/bg11.webp；也可换成本地封面	可选	目录页封面元数据。推荐复用已有图片；如果要使用自定义路径，必须确认文件真实存在。

复制后必须修改或确认

字段	操作	示例	说明
title	必须改	项目记录	改成目录的真实名称。
description	必须改	项目开发、架构设计和复盘记录。	写清这个目录收录什么，建议 50–150 个中文字符。
layout	固定	page	目录页必须使用页面布局。
catalogue	固定	true	目录页必须开启自动目录。
path	必须改	posts/技术笔记/项目记录	指向真实存在的 docs/posts/ 目录，不加前导斜杠。
pageTitle	建议确认	文档目录	可改成更具体的列表标题，例如 项目记录。
permalink	必须改	/catalog/技术笔记/项目记录	与目录路径一一对应且全站唯一。
sidebar	固定	false	目录页不显示文章侧边栏。
article	固定	false	目录页不进入文章区域。
pagefind-indexed	固定	false	目录页不进入站内搜索。
comment	固定	false	目录页不显示评论。
coverImg	建议确认	/home/bg11.webp	可选，但填了就必须确认文件存在。

目录页不要写 categories、tags、date、top、sticky。它不是文章，不需要文章分类、标签、发布时间、精选或置顶。

新目录页建议只保留 description，不要再添加旧字段 desc。如果仓库已有目录页同时保留 desc，保持其原样即可，但不要把两者写成不同内容。

path 与 permalink 公式

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

一级分类示例：

文件：docs/catalog/技术笔记.md
path：posts/技术笔记
permalink：/catalog/技术笔记

二级目录示例：

文件：docs/catalog/技术笔记/项目记录.md
path：posts/技术笔记/项目记录
permalink：/catalog/技术笔记/项目记录

必须遵守以下细节：

• path 推荐统一写成相对 docs/ 的 posts/...；不要写 docs/posts/... 或绝对磁盘路径。前导 / 在当前插件通常仍可解析，但团队约定不使用。
• path 指向 docs/posts/ 下真实存在的目录，不是 docs/catalog/。
• permalink 以 /catalog/ 开头，不带 .md，建议不加末尾斜杠。
• permalink 必须全站唯一，目录页与目录页、文章之间都不能重复。
• title、path 的末级目录名、permalink 的末级路径最好保持一致，便于排查。
• 目标目录暂无文章时可以保留 .gitkeep，但仍不要创建 index.md。

目录页的页面结构

目录页没有正文内容，也没有推荐章节。复制模板时，只要保留 frontmatter 和成对的 ---，不要在闭合的 --- 后面添加 H1、H2、列表或说明文字。

页面上的文章列表、子目录和标题都由 catalogue: true 与 path 自动生成。title 和 pageTitle 是 frontmatter 字段；不要为了在页面中间增加说明而改写成普通文章。目录页也不遵循通用的「背景、目标、总结」章节建议，因为它本来就没有正文。

重启开发服务器

Teek 的目录数据在 Vite 启动阶段扫描。新增、删除或修改 catalogue: true 页面，修改 path，或者调整被扫描的文章目录结构后，如果目录页没有立即更新，请停止开发服务器并重新运行：

pnpm docs:dev

当前开发端口为 5174。不要只刷新浏览器就认为配置一定已经重新扫描。发布前还应运行构建：

pnpm docs:build

发布前检查

• 文件位于 docs/catalog/，没有放到 docs/posts/。
• 文章目录真实存在，且没有 index.md。
• layout: page。
• catalogue: true。
• path 以 posts/ 开头并指向正确目录，没有 docs/ 段或反斜杠。
• permalink 以 /catalog/ 开头、全站唯一、与路径对应。
• sidebar: false、article: false、pagefind-indexed: false、comment: false 均保留。
• 没有写 categories、tags、date、top、sticky。
• coverImg 指向真实存在的图片。
• 闭合的 --- 后没有任何正文。
• 重启开发服务器后，目录能列出目标文章和子目录。
• 目录页没有左侧栏、评论和搜索结果。
• 新增一级分类时已同步检查导航、侧边栏和搜索分类顺序。