管理您的文档站点

本指南介绍网站上线之后的操作：修改页面、撤销更改、决定谁可以阅读，以及诊断网站未获取最新提交的问题。如果您还没有发布网站，请先从创建您的第一个文档站点开始。

打开管理小组件#

登录并打开您自己的网站。右下角会出现一个管理小组件：

+----------------------+
| Your name            |
|                      |
| Select chat        > |
| Select repo        > |
| Select mode        > |
|                      |
| Settings             |
| Sign out             |
+----------------------+

点击您的头像或设置以打开设置面板。本页面中所有标有“设置”的内容都从这里开始。

读者永远不会看到此小组件。退出登录的访客只能看到您的文档、设计和内容，看不到任何控件。

您可以在设置中配置的内容#

从 GitHub 更新页面#

1. 在 github.com 上打开您的代码仓库。
2. 打开 Markdown 文件，然后点击铅笔图标。
3. 进行更改，然后点击提交更改。

您的网站会自动获取提交内容。无需重新部署。

使用 git 从计算机更新页面#

当你同时修改多个文件并希望一并进行审阅时，可以使用此方法。

git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
cd YOUR_REPO

在编辑器中编辑文件，然后发布：

git add docs/
git commit -m "Update the installation guide"
git push origin main

删除页面的流程相同：删除文件、提交、推送。页面会从网站和侧边栏中消失。

无需离开浏览器即可编辑页面#

对于小幅更正，你既不需要 GitHub，也不需要本地检出 — 直接编辑你正在阅读的页面。

1. 在 Docsbook AI 聊天中打开项目，并在旁边显示预览（分屏视图）。
2. 将预览上方的栏从预览切换为编辑。
3. 点击你想要更改的块。

打开的面板可以使用 AI 重写该块、直接编辑其文本、缩短或扩展内容、将其转换为内容小组件，或将其删除。拖动块的手柄即可移动它；在你点击保存或还原之前，系统会预览新的顺序。

如果你想添加内容而不是进行更改，请将指针移到两个块之间的接缝处。此时会出现一个加号按钮，并提供段落、标题、列表、代码块、引用、提示框、表格或小组件选项。侧边栏底部的添加页面可以根据标题、文件夹以及关于页面应涵盖内容的可选备注创建整个页面。

所有这些操作都会像其他更改一样提交到你的代码库，因此你的源内容始终是唯一的事实来源。使用 AI 重写块会调用模型，并从项目余额中扣费；自行编辑文本则不会。

撤销您发布的更改#

助手发布的任何更改都可以直接从聊天中撤回，无需打开 GitHub。

• 立即撤销：点击助手发布后显示的卡片上的撤销箭头（“已更新 2 个文件”）。
• 稍后撤销：点击聊天标题中的时钟图标。该图标会列出项目最近的更改及每项更改涉及的文件，并在每个条目旁提供撤销选项。

该历史记录就是存储库的真实发布历史，因此也会列出在较早会话中、由团队成员或直接在 GitHub 上进行的更改。所有更改都可以用相同的方式撤销。

撤销操作会生成一个新的提交，将文件恢复原状，而不是重写历史记录。它会作为单独的条目出现在列表中，并标记为撤销；该操作本身也可以撤销，并且绝不会丢弃其他人的提交。如果无法读取某个文件的早期版本，系统会将其报告为已跳过，而不是擅自猜测。

询问助手需要改进的地方#

询问助手需要修复什么——“我应该先修复什么”、“让这个内容能在搜索中被找到”、“这些页面内容感觉太单薄了”——答案会以待勾选的列表返回，而不是需要你手动执行的文字说明。

每一行都是对某个真实页面的一项具体更改：更改内容、带来的帮助，以及涉及的页面。有些行是设置项而不是重写内容，打开对应卡片即可切换。列表开始时不会勾选任何项目。勾选所需的行，按一次 应用，所有勾选的行就会一次性完成。未勾选的行绝不会被写入。

这个列表并非凭空猜测：助手会读取涵盖你所提问题的文档技能——搜索与索引、语气、无障碍、翻译——检查它能衡量的网站信息，检查现有的设置卡片，并根据这些结果提出建议。它会说明所应用的技能。

应用的具体操作取决于自动模式：

生成列表和重写页面都会调用 AI 模型，因此两者都会从项目余额中扣费。

了解侧边栏顺序#

Docsbook 会读取文件名来排列侧边栏：

• 以读者入门为目的的页面——README、introduction、getting-started、quick-start、installation、setup——会被列在最前面。
• 用于查找信息的页面——reference、api、changelog、faq、troubleshooting——会被列在最后面。
• 其他内容会按字母顺序排列在两者之间。文件夹也会以相同方式根据自身名称排序。

因此，数字前缀仍然有效：按字母顺序排列时，1-basics.md 会排在 2-intermediate.md 之前；Docsbook 根据上述两个列表检查名称时会忽略数字。

如果没有页面匹配任一列表，侧边栏就会按纯字母顺序排列。重命名文件即可移动其位置。

将文件整理到文件夹中#

侧边栏反映你的文件夹结构，因此文件夹结构就是导航。按主题分组：

docs/
├── README.md
├── getting-started.md
├── api/
│   ├── overview.md
│   ├── auth.md
│   └── endpoints.md
└── guides/
    ├── deployment.md
    └── troubleshooting.md

按主题分组优于按难度分组（1-basics.md、2-advanced.md），因为读者通过搜索引擎到达页面时，寻找的是某个主题，而不是某个级别。

页面之间的链接#

编写普通的相对 Markdown 链接。Docsbook 发布时会将其转换为网站 URL。

[Set up a custom domain](/docsbook-io/docs/guides/advanced/custom-domain)
[Create your first site](/docsbook-io/docs/guides/getting-started/creating-docs)
[Frequently asked questions](/docsbook-io/docs/faq)

使用其锚点链接到同一页面上的标题：

[Jump to the sidebar order](#understand-the-sidebar-order)

锚点是小写的标题文本，并将空格替换为连字符，因此该标题必须存在，链接才能跳转到正确位置。

添加图片#

1. 将图片文件放在仓库中页面旁边，例如放在 images/ 文件夹中。
2. 提交它。
3. 使用相对路径引用它，并描述图片展示的内容：

![GitHub fork dialog with the Create fork button highlighted](https://raw.githubusercontent.com/docsbook-io/docs/main/guides/getting-started/images/fork-dialog.png)

PNG、JPG、GIF 和 WebP 均可正常渲染。请为每一张承载信息的图片编写真实的替代文本——屏幕阅读器会朗读这些文本，搜索引擎会将其编入索引，文件加载失败时读者也会看到这些文本。

控制谁可以阅读您的文档#

默认情况下，Docsbook 站点是公开的：任何拥有链接的人都可以阅读，搜索引擎爬虫会将其编入索引，并且不需要 GitHub 帐户。即使源代码仓库是私有的，这一点也同样适用。

要关闭公开访问，请在设置 → 隐私 & 访问权限中将工作区切换为私有。之后，读者必须使用共享密码解锁，或通过您自己的 OIDC 身份提供商登录——爬虫也包括在内。您作为所有者始终拥有访问权限。完整设置方法：限制谁可以阅读您的文档站点。

与其他人协作#

通过 GitHub。 将他们添加为仓库协作者。他们可以编辑文件或发起拉取请求，当更改进入你的默认分支后，网站就会更新。对于已经在仓库中协作的人员，这是合适的方式。

通过 AI 聊天。 点击聊天工具栏中的邀请，然后发送电子邮件邀请或链接。协作者会加入同一个实时会话，因此不需要 GitHub 账户。他们的工作使用的项目余额与你相同。

修复未更新的网站#

请按以下顺序逐项排查。

1. 确认提交已到达 GitHub。 打开存储库并查找该提交。如果找不到，说明它从未被推送。
2. 跳过浏览器缓存重新加载。 按 Ctrl+F5；在 macOS 上按 Cmd+Shift+R。使用隐私窗口是排除缓存影响最快的方法。
3. 等待几分钟。 发布不是即时完成的；Docsbook 会定期检查存储库，而不是在每次按键时检查。
4. 检查文件扩展名。 只有 .md 文件会被发布。
5. 检查文件名。 拉丁字母、数字和连字符是安全的；其他字符可能无法生成 URL。

如果某些页面已更新而其他页面没有更新，几乎总是浏览器缓存导致的，而不是同步问题——部分更新并不是 Docsbook 会发布的状态。

版本控制#

Docsbook 为你的文档提供一个版本：分支的当前状态。目前不支持并行发布多个版本。

如果你现在需要多个版本，请将版本保存在不同的分支（docs/v1、docs/v2）或不同的仓库中，然后连接你想要发布的版本。

查看谁在阅读#

打开浮动小组件 → 分析。系统会按页面报告浏览量、访客、热门页面、引荐来源和搜索查询，因此你可以查看哪些页面获得了流量，哪些页面无人阅读。

关于页面的大多数问题，以下两份报告可以给出答案：用于了解流量的网站分析，以及用于了解访问者是否获得所需信息的页面反馈。

删除工作区#

设置 → 删除工作区会移除文档站点及其上的所有设置。此操作无法撤销。

您的 GitHub 仓库不会受到影响。Markdown 文件仍保留在原来的位置，因此删除工作区会丢失配置，而不会丢失内容。

后续步骤#

• 设置自定义域名 — 从你拥有的地址提供文档。
• 翻译文档 — 15 种语言，每种语言分别建立索引。
• Docsbook 包含什么以及哪些内容收费 — 哪些操作会使用项目余额。
• 常见问题 — 读者在做出决定前提出的问题。