Docsbook 常见问题：成本、限制、同步和数据所有权
问题按其阻碍决策的先后顺序排列：先谈费用，然后是入门，最后是产品运行后的行为方式。
费用和计费#
Docsbook 的费用是多少？#
Docsbook 会对四项内容进行计量，它们全部属于 AI 工作，费用从发起请求的项目余额中扣除：
- 读者（AI 聊天） — 为文档读者提供的 AI 答案。
- 管理员 & AI 代理 — 由你或已连接的代理启动的一次代理运行。
- AI 翻译 — 将页面翻译成另一种语言。
- 语义索引 — 构建 AI 聊天所检索的嵌入。
其他所有内容均不计量：网站托管、自定义域名及其 TLS 证书、读者浏览、编辑者撰写内容、GitHub 同步、全文搜索、品牌设置、分析和 MCP 读取调用。当前的费用数据请参阅 docsbook.io/pricing，该页面每次请求都会根据 Docsbook 的计费常量生成 — 请以该页面上的价格为准，而不要参考可能过时的文档页面。有关其机制，请参阅定价。
有免费试用 Docsbook 的方式吗？#
有。生成草稿网站无需账户或信用卡：在 docsbook.io/start 粘贴代码仓库、网站 URL 或一句关于您产品的描述，然后登录前即可查看结果。之后，每个新项目都会获得 $1.00 的余额；项目创建满 3 分钟 后，还可以领取额外的 $5.00。这两笔金额都是真正可用于 AI 工作的额度。
我如何开始消费，充值需要多少钱？#
Docsbook 项目一开始就有的 $1.00 可立即使用——向 AI 聊天提问，你就会看到余额减少。项目创建满 3 分钟后，在项目的账单卡片上按下领取，即可添加$5.00欢迎额度；不会有人代你添加。
之后，充值金额由你自行决定。单次充值最低为$20.00，最高为$5,000.00；如果需要更多金额，请分两次充值。这笔钱会记入你所选的一个项目的余额。余额不会按计划自动补充——如果你希望定期充值，请在账单页面设置每月付款。
项目余额用尽时会发生什么？#
文档网站仍保持在线。读者可以继续浏览，全文搜索继续正常工作，GitHub 同步继续运行，并且不会删除任何内容。停止的是按量计费的 AI 工作：调用会在执行前被拒绝，并说明哪个项目余额已用尽、该调用原本会花费多少、还剩多少，以及在哪里为该项目充值。
通过 MCP 进行的免费发现调用仍可正常工作，因此代理仍能报告发生了什么，而不会静默失败。
我可以停止付费吗？停止后我的文档网站会怎样？#
无需取消任何内容：你可以在需要时为项目余额充值，停止付费意味着不再继续充值。你的文档网站仍会在线，地址为 docsbook.io/{owner}/{repo}；你的 Markdown 仍保存在自己的 GitHub 仓库中，并且你的设置——品牌、导航、布局——都会保留。不会删除任何内容。
如果你自行设置了每月定期付款，请前往 docsbook.io/chat 的账单页面终止付款。
我的文件仍归我所有吗？#
是的。您的 Markdown 始终存储在您自己的 GitHub 存储库中。Docsbook 会渲染这些文件；它不会将您的内容存储为专有格式，也无需先导出任何内容。将另一个文档工具指向同一个存储库，您可以保留每个页面、图像和链接。
如何支付 Docsbook？#
账单由 Paddle 处理，Paddle 是记录商家。请从 docsbook.io/chat 的控制面板打开账单页面，并为项目充值余额——最低 20.00 美元，最高 5,000.00 美元。支持 Visa、Mastercard、American Express、Apple Pay 和 Google Pay。
支付安全吗？#
安全。支付由作为记录商户的 Paddle 处理，Docsbook 永远不会看到您的卡号。整个结账流程都在 Paddle 自己托管的页面上完成。
一个账户可以运行多个文档站点吗？#
可以。一个 Docsbook 账户可以拥有多个项目，每个项目都有自己的余额。一个项目余额用尽不会影响另一个项目。哪一个项目为计量调用付费，取决于调用本身——您指定的工作区，或调用所限定的代码仓库。
你们提供退款吗？#
请发送邮件至 support@docsbook.io，并提供您的账户地址以及您购买的内容。退款由处理付款的 Paddle 逐案处理。
组织是否有折扣？#
请发送电子邮件至 support@docsbook.io 与我们讨论。这里没有可供引用的已公布组织折扣。
开始使用#
尝试 Docsbook 需要 GitHub 仓库吗？#
不需要。在 docsbook.io/start，一个输入框可以接受你已有的任何内容——网站 URL、仓库链接、PDF 或屏幕截图，或者一句关于你所销售产品的描述——并据此生成一个网站草稿。你会进入草稿的管理面板，文档触手可及；在创建帐户之前，你可以修改品牌、布局和 SEO。
只有在关联现有仓库或发布时才需要 GitHub。任何登录方式都可以：GitHub、Google、Apple，或使用一次性代码登录的电子邮箱。
Docsbook 需要什么类型的仓库？#
任何包含 Markdown 文件的 GitHub 仓库都可以。这可以是一个单独的 README.md、一个 docs/ 文件夹、一份 API 参考文档，或一堆扁平的 .md 文件——Docsbook 会根据现有的任何结构构建导航。
我需要在 GitHub 中配置任何内容吗？#
不需要。通过 GitHub OAuth 授权 Docsbook 后，它会读取仓库文件。无需添加工作流文件、安装 GitHub Action，也无需注册 Webhook。
我应该使用什么文件夹结构？#
任何结构都可以，因为 Docsbook 会根据找到的文件夹构建导航树。一种常见的结构：
repo/
├── README.md
├── docs/
│ ├── getting-started.md
│ ├── api/
│ └── guides/文件夹根目录中的 README.md 会成为该文件夹的首页。
我可以使用 .markdown 而不是 .md 吗？#
可以。Docsbook 会读取 .md 和 .markdown。其他格式的文件（.txt、.rst、.adoc）不会转换为页面。
Markdown 文件之间的链接有效吗？#
是的。Markdown 文件之间的相对链接会解析为已发布的 URL，因此在 GitHub 上有效的链接在网站上也有效。请按照你原来的方式编写：
[Concepts](/docsbook-io/docs/basics)
[Custom domain](/docsbook-io/docs/guides/advanced/custom-domain)指向页面内标题的锚点（./basics.md#indexing）同样会解析。
如何将图片添加到我的文档中？#
将图片文件放入您的代码仓库中——docs/images/ 是一种常见选择——并使用相对路径引用它。PNG、JPG、GIF 和 WebP 均可正常提供。
替代文本是屏幕阅读器和 AI 爬虫读取的内容，因此请描述图片所展示的内容，而不是给文件命名。
我可以在 Markdown 中使用 HTML 吗？#
可以。Markdown 支持内联 HTML，Docsbook 也会对其进行渲染。纯 Markdown 仍然是更好的默认选择，因为它在 GitHub、编辑器中以及通过 MCP 由代理读取时都能正常保留。
如何在 GitHub 账户和组织之间切换？#
点击 AI 聊天右上角的 GitHub 按钮。它会打开一个切换器，列出您已登录的账户以及您所属的每个 GitHub 组织。按钮上的绿色圆点表示 GitHub 已连接。将鼠标悬停在任意账户或组织上——在触摸屏上则点击——即可查看其代码仓库，并从那里将其中一个连接为新项目。
我可以将 Docsbook 托管的项目迁移到自己的 GitHub 仓库吗？#
可以，在同一个 GitHub 按钮中操作。Docsbook 会在你的账户中创建仓库，将每个页面一次性复制到其中并提交，然后将项目指向该仓库；之后你的编辑会直接提交到自己的仓库。
迁移前请注意两个后果：公开 URL 会发生变化，之前的托管地址将停止工作且不会重定向，因此请更新所有你曾分享过该地址的地方。此外，迁移是单向的——没有按钮可以将项目迁移回 Docsbook 托管。
发布与同步#
如何更新我的 Docsbook 文档？#
编辑 Markdown 文件并将其提交到 GitHub。网站会在下次访问时获取更改——无需触发构建，也无需等待部署。你也可以在 Docsbook 的网页编辑器中编辑，或通过 MCP 使用代理进行编辑；这三种方式都会以提交的形式保存到同一个仓库中。
Docsbook 网站在推送后多久更新？#
下次访问时。Docsbook 会在网站加载时检查 GitHub 是否有新的提交，并重新索引发生变化的内容，因此您打开的页面是根据当前仓库状态构建的，而不是来自缓存的构建版本。
为什么我的 Docsbook 网站没有更新？#
请按顺序逐一检查以下四项：
- 提交是否确实已在 GitHub 上？请在 github.com 上检查该文件。
- 你是否对浏览器执行了强制刷新（Ctrl+F5 或 Cmd+Shift+R）？
- 提交后是否已经过去一两分钟？
- 文件是否以
.md或.markdown结尾？其他扩展名不会被索引。
如果这四项都没有问题，请将仓库和提交信息发送至 support@docsbook.io。
Docsbook 网站搜索是否有效？#
是的。每个 Docsbook 网站都内置了覆盖所有页面的全文搜索功能。点击页眉中的搜索图标，或在 macOS 上按 Cmd+K，在 Windows 和 Linux 上按 Ctrl+K。
有深色主题吗？#
有。支持浅色、深色和跟随系统的主题。工作区所有者可在品牌设置中选择默认主题，读者则可以通过页眉中的主题切换按钮进行切换。
Docsbook 网站可以承载多少并发访问者？#
Docsbook 网站由 Vercel 的 CDN 提供服务，该 CDN 会自动扩展。无需配置访问者上限，也无需购买流量套餐。
访问与隐私#
谁可以查看我的 Docsbook 文档？#
默认情况下，所有人都可以查看：任何拥有链接的人、没有 GitHub 帐户的人，以及搜索引擎爬虫。这通常正是你想要的，因为公开网站会被 Google 编入索引，AI 助手也可以引用其中的内容。
你可以更改此设置——请参阅下一个答案。
我可以将文档设为私有吗？#
可以。将工作区切换为私有后，读者看到的将是解锁屏幕，而不是您的内容；解锁方式可以是共享密码，也可以是您自己的 SSO 身份提供商。在读者解锁之前，文档结构、页面和搜索索引都会保持隐藏状态，而所有者始终拥有完整访问权限。
有关设置，请参阅私有文档：密码和 SSO。
私有 GitHub 仓库会使已发布的网站变为私有吗？#
不会。这两个设置彼此独立。Docsbook 通过您授予的 GitHub 授权读取仓库，然后提供其构建的页面；谁可以读取这些页面由 Docsbook 自身的访问设置决定，而不是由仓库的可见性决定。
我的文档是否通过 HTTPS 提供服务？#
是的。每个 Docsbook 网站都通过 Vercel 的 CDN 使用 HTTPS 提供服务，自定义域名会自动配置其 TLS 证书。
其他人可以通过 Docsbook 编辑我的文档吗？#
除非你授予他们仓库访问权限。Docsbook 会将更改作为提交写入构建网站所使用的仓库，因此仓库权限决定了谁可以更改哪些内容。
谁能看到浮动小组件？#
只有您在登录并查看自己的文档时才能看到。读者只能看到文档本身，除此之外什么也看不到——浮动小组件根本不会为他们呈现。
自定义域名#
如何为 Docsbook 使用我自己的域名？#
在工作区设置中输入域名，在 DNS 服务商处添加 Docsbook 显示给你的 CNAME 记录，然后等待其完成传播。Docsbook 会自行配置 TLS 证书。
完整指南：自定义域名设置。
通常使用子域名#
通常使用子域名 — docs.example.com。它只需一条 CNAME 记录，并且不会影响营销网站使用的顶级域名。根域名也可以，多个指向不同工作区的子域名同样可以。
我需要自行设置 SSL 吗？#
不需要。Docsbook 会自动为您的自定义域名配置和续订 TLS 证书，无需额外付费，也无需您进行任何配置。
DNS 传播需要多长时间？#
通常需要 15 到 30 分钟，最坏情况下可能需要 48 小时。延迟出现在您的 DNS 提供商处，而不是 Docsbook — 记录解析后，域名便会立即开始提供服务。
翻译#
如何翻译我的 Docsbook 文档？#
打开您的工作区设置，选择目标语言，然后保存。Docsbook 会翻译页面，并为每种语言提供独立的路由。翻译由 AI 完成，因此会消耗项目余额。
完整操作指南：翻译 & 国际化。
Docsbook 支持哪些语言？#
15 种：英语、西班牙语、法语、德语、葡萄牙语、意大利语、俄语、中文、日语、韩语、阿拉伯语、印地语、土耳其语、波兰语和荷兰语。每种语言都有自己的路由，并使用正确的 hreflang 标签，因此搜索引擎会将其作为单独的页面进行索引。
Docsbook 的 AI 翻译效果如何？#
对于技术文档来说，翻译质量足以直接发布，因为其中的词汇一致且句子简短。习语、笑话和具有文化特色的示例则需要人工校对——在宣布支持该语言之前，请先阅读这些页面。
当我更新原文时，翻译会更新吗？#
会。当源页面发生更改时，Docsbook 会重新翻译该页面，因此语言版本不会在不知不觉中偏离英文版本。
我可以手动编辑翻译吗？#
可以。您可以下载翻译，进行修正，然后重新上传。如果您希望有人指导整个流程，请发送电子邮件至 support@docsbook.io。
AI 与代理#
SEO、GEO 和 AEO 是什么？它们为什么对文档很重要？#
SEO 让您的文档出现在 Google 的搜索结果中。GEO——生成式引擎优化——让文档出现在 AI 的回答中：Perplexity 引用、ChatGPT Search、Google AI Overviews。AEO——答案引擎优化——添加精选摘要和语音助手读取的结构化标记。
Docsbook 根据您的 Markdown 生成这三者：元标签、sitemap.xml、OpenGraph、规范 URL、TL;DR 区块、可见的 dateModified、作者标记、FAQPage 和 HowTo JSON-LD，以及可朗读选择器。请参阅 SEO、GEO 和 AEO。
什么是 Docsbook 技能？#
Docsbook 技能是教会 AI 代理如何执行文档工作的一组 SKILL.md 文件。该目录包含四项编排技能，每项对应一项任务：docs-analyze 查找问题，docs-create 编写缺失内容，docs-manage 决定页面应表达的内容，而 docs-automate 让其中任何一项工作重复执行。
使用 npx skills add Docsbook-io/docs-skills --skill '*' 安装它们，或者让通过 MCP 连接的代理在运行时使用 find_skill 发现它们。请参阅 Docs 技能。
AI 代理可以编辑我的文档吗？#
可以。Docsbook 的 MCP 服务器在 https://docsbook.io/api/mcp/server 提供 309 个工具，因此 Claude Code、Cursor 或 ChatGPT 可以读取您的页面、搜索页面、修改设置，并将新页面提交回来。写入操作需要使用具有读写权限范围的令牌进行授权；只读令牌将被拒绝。
从其他工具迁移#
如何从 GitBook 迁移到 Docsbook？#
分为三步：
- 从 GitBook 导出。GitBook 可以同步到 Git 仓库，或将 Markdown 导出为
.zip。将生成的.md文件推送到 GitHub 仓库——任何结构均可。 - 连接仓库。在 docsbook.io/start 粘贴
github.com/your-org/your-repo。 - 重新指向您的域名。在 GitBook 中移除自定义域名，在 Docsbook 中添加该域名，并更新 CNAME 记录。TLS 证书会为您自动配置。
会自动迁移的内容：页面结构、内部链接（相对的 .md 路径会被解析）、图片、GFM 代码块、标题和 frontmatter。需要重新设置的内容：品牌元素、导航链接以及 AI 聊天中的建议问题。并排对比：GitBook 与 Docsbook。
如果 Docsbook 停止运营，我的文档会怎样？#
不会丢失任何内容。您的 Markdown 文件存储在您自己的 GitHub 仓库中，采用开放格式，并保留其历史记录。将其他工具指向同一个仓库，您即可保留所有内容——不存在需要摆脱的专有存储，也无需申请导出。
支持、法律和技术#
如何联系 Docsbook 支持？#
请发送电子邮件至 support@docsbook.io，或在 Docsbook Discord 中提问。请附上您的项目地址 — docsbook.io/{owner}/{repo} — 这样回答者就能查看正确的网站。
如果出现问题，我该怎么办？#
发送邮件至 support@docsbook.io，并提供三项信息：页面 URL、您预期的结果，以及实际发生的情况。截图会有所帮助；如果问题与未显示的内容有关，提交 SHA 会更有帮助。
在哪里可以查看 Docsbook 产品更新？#
更新日志记录了每项已发布的更改及其预期目标。较短的公告会发布到 twitter.com/docsbook。
Docsbook 是用什么构建的？#
基于 Vercel 上的 Next.js 16、React 19、TypeScript 和 Tailwind CSS，后端使用 Postgres（Neon）和 Redis，ORM 采用 Drizzle，计费使用 Paddle，并通过 GitHub API 访问代码仓库。AI 调用通过 OpenRouter 或您自己的服务提供商密钥进行路由。
Docsbook 数据存储在哪里？#
存储在 Vercel 的基础设施和 Neon Postgres 中，托管于美国及其他地区。您的文档内容本身仍保留在 GitHub 仓库中——Docsbook 存储的是从中构建的索引，而不是您的事实来源的第二份副本。
Docsbook 使用哪种 Markdown 解析器？#
通过 unified 使用 remark 和 rehype，并支持 GitHub Flavored Markdown (GFM)。导航和链接解析使用 markdown-lsp，这是 Docsbook 的开源文档解析器；语法高亮使用 Shiki。
是否有服务条款和隐私政策？#
有：服务条款和隐私政策。如果某个网站违反了条款，Docsbook 会先联系所有者，通常会给予其修复问题的机会，然后才会采取其他措施。