侧边栏配置实用指南

本指南将通过一系列常见的任务，带您了解如何配置和管理 CrychicDoc 的侧边栏。

核心理念：Frontmatter 驱动配置

CrychicDoc 的侧边栏系统通过读取您在 Markdown 文件中设置的 frontmatter 来自动生成配置。您只需要在文档中声明元数据（如 title, priority），然后运行一个脚本，侧边栏就会自动更新。

核心配置字段

为了有效地管理侧边栏，您需要了解以下几个关键的 frontmatter 字段。

字段	类型	描述
root	boolean	将一个目录的 sidebarIndex.md 标记为侧边栏的新根节点。
title	string	必需。侧边栏中显示的标题。
priority	number	必需。排序权重，数字越小，越靠前。
maxDepth	number	控制当前目录视图向下展开的层级深度。
hidden	boolean	如果为 true，则此页面或目录不会显示在侧边栏中。
externalLinks	object[]	在 root 节点中添加指向外部网站的链接。
useChildrenCollapsed	object	只控制当前生成树里子目录项如何折叠或展开，不改写子项自己的 frontmatter。

实践教程：配置一个新文档区

高级技巧与提示

添加外部链接

在根目录 AwesomeMod/sidebarIndex.md 的 frontmatter 中添加 externalLinks。

---
root: true
title: "AwesomeMod 指南"
# ... 其他配置 ...
externalLinks:
  - text: "官方 Wiki"
    link: "https://awesomemod.com/wiki"
    priority: -999 # 使用负数让链接靠前显示
  - text: "GitHub 仓库"
    link: "https://github.com/user/awesomemod"
    priority: -1000
---

使用 useChildrenCollapsed 管理当前树里的子项折叠

如果你的目标只是让当前 root 决定“这一棵 sidebar 里子目录项默认折叠、跟随自己、还是默认展开”，现在只使用 useChildrenCollapsed。

useChildrenCollapsed 的字段约定

字段路径	类型	默认行为	作用
useChildrenCollapsed	object	不写则保持每个子项自己的 collapsed	当前生成树里的子项折叠规则。
useChildrenCollapsed.mode	"children" | "self" | "collapsed" | "open"	children	子项是沿用自己、跟随当前目录、强制折叠，还是强制展开。
useChildrenCollapsed.depth	number	1	影响深度。1 只影响直接子项，2 继续影响孙级。

这个配置只影响当前这次 sidebar 生成树里的显示状态：

• 不会改写子目录自己的 collapsed
• 不会改写子目录自己的 maxDepth
• 不会改写任何子文档 frontmatter
• 不会接管遍历控制，也不会替代 root

最小示例：

---
root: true
title: "Modpack"
useChildrenCollapsed:
  mode: collapsed
  depth: 1
---

这表示当前 root 在这棵树里把直接子目录项默认显示为折叠。

如果你想让子项跟随当前目录自己的 collapsed：

---
root: true
collapsed: true
useChildrenCollapsed:
  mode: self
  depth: 2
---

这会让子项和孙级子项在当前树里都跟随当前目录的折叠状态。

目录落地页文件约定

当一个目录需要可点击的“落地页”时，系统会按顺序查找这些文件：

• index.md
• Catalogue.md
• README.md

这意味着第一方文档仍然可以继续用 Catalogue.md 作为目录页，而站内整理的第三方文档如果本身已经有 README.md，就不需要再额外补一个 Catalogue.md。