进阶使用

文档树以真实目录为准：每个一级目录是一套合集，目录内的 README.md 作为首页，其他 Markdown 文件作为普通页面。目录名称可以使用中文。

建立一套文档

content/docs/product/
├── README.md
├── install.md
└── basics/
    ├── README.md
    └── configuration.md

在工作区执行下面的命令，可以创建同类结构：

bookx new collection "Product"
bookx new doc product/install "安装"
bookx new section product/basics "基础用法"
bookx new doc product/basics/configuration "配置"

每个内容文件都要有独立稳定 ID。合集首页的标题用于合集入口，目录首页的标题用于对应导航节点。顶部文档菜单只列出合集，进入文档后再通过左侧树浏览章节。

同级顺序与永久地址

order 只影响同级页面和目录，数字越小越靠前；同级不能重复设置同一个显式值。工作台的拖动排序会保存顺序，不必另外维护目录列表。目录级状态保存在可扩展的 .bookx.yml 中。

中文名称在未指定 slug 时生成无声调拼音，例如当前“进阶使用”目录对应 jin-jie-shi-yong。多音字或已公开的路径建议显式填写 slug。修改标题不需要更换 ID；改目录或 slug 时要同步检查旧链接，必要时用 aliases 保留旧地址。

只保留子目录，不展示首页

顶级合集必须有首页。只有子目录提供“显示目录首页”开关，默认开启；关闭后保留 README 和目录信息，但不输出该首页。下级页面仍可显示，左侧点击目录名称或箭头展开、收起。

隐藏首页不进入搜索、站点地图、别名或前后章节；没有可见子页面的空分支也会隐藏。面包屑中无首页的节点显示纯文字。已经写入正文的首页链接不会自动改写，关闭前应改为下级页面链接。

草稿、私有与仅本地

文档目录与所在 README 共用私有状态，私有目录会排除整个分支；普通文档可以单独私有。标注“继承自上级”的页面需要在对应上级取消设置，不能只修改子页面来解除继承。

“仅本地”在目录右键菜单设置，保护该目录中的现有内容、附件和以后新增文件。改名后继续保留；取消后可重新参与同步和发布。已进入 Git 的历史不会被自动删除，独立共享图库也不属于该目录的保护范围。

目录与章节导航

文档左侧是合集目录树；正文的“本页目录”来自 Markdown 标题，至少两个标题时显示，可用 toc: false 关闭。它们分别解决“下一章在哪”和“本页读到哪”的问题。

内置主题在桌面展示文档侧栏，窄屏通过目录抽屉打开。目录按层级缩进，当前页面以下划线标识；正文目录随滚动高亮。前后章节只包含可展示的页面。

常见问题

• 文章或章节不见了：先检查草稿、私有、仅本地及上级继承状态，再确认使用的是哪一种预览。
• 关闭首页后构建报链接错误：查找正文中仍指向该 README 的链接，改为可见页面。
• 本地和 CI 日期不同：显式填写带时区的创建／更新时间；使用 Git 时间时保证构建环境有完整历史。
• 页面改名后旧链接失效：保留 ID 只能保留身份，不会自动保留旧 URL；检查 slug、目录和别名。

返回使用手册，或继续阅读同步与发布。