1. 为什么我最终把文档站换成了 mdbook如果你手头有一堆 Markdown 笔记、项目文档或者教程想快速变成一个能本地预览、又能直接发布成静态站的“书”mdbook 是我目前最愿意推荐的工具。它是 Rust 官方团队维护的开源项目核心逻辑很朴素你写 Markdown它负责把章节组织成一本结构清晰的书最后输出纯静态 HTML。没有数据库、没有后端、没有花哨的运行时依赖构建产物丢到任何静态托管上都能跑。它适合谁我总结了三类一是写技术教程、想按章节组织的开发者二是项目需要一份可版本管理的文档站又不想引入重型框架三是已经在用 Rust 生态、希望工具链统一的人。mdbook 的配置只有一个book.toml章节结构靠SUMMARY.md描述学习成本低到几乎可以忽略。但实际写书过程中我遇到一个很现实的问题AI 辅助写作越来越常用可每个工具都要单独填 API Key、单独配模型地址写文档时切来切去很烦。所以我后来用 TaoToken 做统一 Key 管理把写作工具和 mdbook 构建流程串起来。这篇就按“装工具 → 配 Key → 写配置 → 构建验证 → 排错”的顺序把整套流程讲清楚你照着做就能跑通。2. TaoToken 前置准备统一 Key 怎么拿、怎么用在进入 mdbook 配置之前先把 Key 这件事解决掉。TaoToken 的作用是提供一个统一的 API 入口让你在多个 AI 写作/编码工具里复用同一套 Key而不用每个工具都去单独申请和管理。对写书场景来说这意味着你在编辑器里让 AI 帮你润色章节、补全示例代码时走的是同一个入口。第一步是拿到 Key。访问官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册登录后进入控制台。控制台地址是 https://taotoken.net/console 在这里可以创建和管理你的 API Key。创建完成后去 API Keys 页面 https://taotoken.net/api-keys 复制你的 Key注意它通常只完整显示一次先存到安全的地方。第二步是确认 API 入口。TaoToken 的 API 基础地址是 https://taotoken.net/api 注意这个地址不带任何查询参数。后面在工具配置里填的base_url就是它很多工具要求填到/v1这一层具体看工具文档但根地址认准这个。注意Key 属于敏感凭证不要写进会提交到 Git 的book.toml或任何公开文件里。建议放在本地环境变量或工具的私有配置文件中。如果你只是想先验证 Key 能不能用可以直接用模型对话页面 https://taotoken.net/model-chat 发一条消息测试确认返回正常再往下走。这一步能省掉后面很多“到底是 Key 错还是配置错”的排查时间。3. 安装 mdbook 并生成第一本书的骨架mdbook 是 Rust 写的最省事的安装方式是通过 Cargo。如果你还没装 Rust 工具链先去官网按提示装好rustup然后执行cargo install mdbook装完后验证一下版本确认命令可用mdbook --version接下来初始化一本书。找一个空目录执行mdbook init my-book cd my-book执行init时它会问你几个问题比如是否创建.gitignore、是否生成示例章节按需选择即可。初始化完成后目录结构大致是这样my-book/ ├── book.toml ├── src/ │ ├── SUMMARY.md │ └── chapter_1.mdbook.toml是全书配置src/SUMMARY.md是章节目录src/下放各个 Markdown 文件。这个结构就是 mdbook 的全部核心理解这两点后面就顺了。4. 可复制的 book.toml 骨架与 settings.json 配置先给一份我实际在用的book.toml骨架你可以直接复制后按需改[book] title 我的技术书 authors [你的名字] description 用 mdbook 构建的 Markdown 书籍 language zh-CN src src [build] build-dir book create-missing true [output.html] default-theme light preferred-dark-theme navy git-repository-url https://github.com/yourname/your-repo edit-url-template https://github.com/yourname/your-repo/edit/main/{path} [output.html.search] enable true几个参数说明一下src指向 Markdown 源目录build-dir是构建产物目录create-missing true表示SUMMARY.md里列了但文件不存在时自动创建写书时很省事。output.html.search打开后构建出的书自带搜索框。然后是 AI 写作工具的配置。很多编辑器类工具用settings.json管理模型接入下面是一个通用片段把 Key 和入口换成你自己的{ ai.provider: openai-compatible, ai.baseUrl: https://taotoken.net/api, ai.apiKey: 你的_TaoToken_Key, ai.model: claude-sonnet-4-20250514, ai.temperature: 0.3 }这里baseUrl填 TaoToken 的 API 根地址apiKey填你在 API Keys 页面拿到的 Key。不同工具字段名可能略有差异比如有的叫endpoint、有的叫apiBase认准“基础地址 Key”这两个核心项即可。温度调低一点0.3 左右更适合写技术文档输出更稳。提示如果你用的是 Claude Code 这类编码代理工具接入方式略有不同可以参考 https://taotoken.net/claude-code-anthropic 的说明长期做编码和 Agent 任务的话Coding Plan 页面 https://taotoken.net/coding-plan 有更合适的方案。5. 构建与本地预览验证build 和 serve 都要跑配置写好后先跑构建确认没有语法或结构错误mdbook build成功的话终端不会有报错当前目录下会多出一个book/文件夹里面是完整的静态 HTML。如果SUMMARY.md里引用了不存在的文件而你又没开create-missing这一步就会报错正好用来检查章节结构。接着启动本地预览服务mdbook serve --open--open会自动打开浏览器默认地址是http://localhost:3000。serve的好处是带热重载你改完 Markdown 保存浏览器会自动刷新写书体验很顺。这里有个我踩过的坑serve用的是内存里的实时构建而build是落盘产物两者理论上一致但如果你改了book.toml里的输出配置最好停掉serve重新跑一次避免看到旧配置的效果。验证“本地预览与构建产物一致”的方法很简单先mdbook build然后用任意静态服务器指向book/目录比如python3 -m http.server 8080 --directory book打开http://localhost:8080对比serve下的页面。如果搜索、主题切换、章节跳转都正常说明产物没问题可以直接部署了。6. 本篇常见错误排查报错一mdbook: command not found。说明 Cargo 的 bin 目录不在 PATH 里。Rust 默认装在~/.cargo/bin把它加进环境变量或者重新打开终端再试。报错二SUMMARY.md里的链接 404。检查文件名大小写Linux 下大小写敏感Chapter_1.md和chapter_1.md是两个文件。另外确认路径是相对src/的。报错三AI 工具返回 401 或鉴权失败。大概率是 Key 填错或baseUrl写成了带路径的地址。确认baseUrl是https://taotoken.net/apiKey 没有多余空格。可以先去模型对话页面发一条消息排除 Key 本身的问题。报错四serve端口被占用。默认 3000 端口常被其他前端项目占用用mdbook serve -p 3001换端口即可。报错五构建产物里搜索不工作。检查book.toml里[output.html.search]的enable是否为true改完必须重新buildserve的热重载不一定覆盖配置变更。7. 把写作和构建串成一条顺手的流水线整套流程跑下来我的实际用法是这样的mdbook 负责结构和发布TaoToken 统一 Key 负责让 AI 写作工具随时可用。写新章节时先在SUMMARY.md里加一行靠create-missing自动生成文件然后在编辑器里让 AI 帮忙补内容保存后serve自动刷新看效果定稿前跑一次build确认产物。如果你后面要长期用 AI 辅助编码和文档生成建议把 Key 管理集中到 TaoToken 控制台 https://taotoken.net/console 统一维护接入细节看文档 https://taotoken.net/doc 需要新建或轮换 Key 就去 https://taotoken.net/api-keys 。这样无论换哪个写作工具配置都只是改一个baseUrl加一个 Key 的事不用重复折腾。 用 mdbook + Rust 打造 Markdown 书籍：TaoToken 统一 Key 配置与本地预览验证
1. 为什么我最终把文档站换成了 mdbook如果你手头有一堆 Markdown 笔记、项目文档或者教程想快速变成一个能本地预览、又能直接发布成静态站的“书”mdbook 是我目前最愿意推荐的工具。它是 Rust 官方团队维护的开源项目核心逻辑很朴素你写 Markdown它负责把章节组织成一本结构清晰的书最后输出纯静态 HTML。没有数据库、没有后端、没有花哨的运行时依赖构建产物丢到任何静态托管上都能跑。它适合谁我总结了三类一是写技术教程、想按章节组织的开发者二是项目需要一份可版本管理的文档站又不想引入重型框架三是已经在用 Rust 生态、希望工具链统一的人。mdbook 的配置只有一个book.toml章节结构靠SUMMARY.md描述学习成本低到几乎可以忽略。但实际写书过程中我遇到一个很现实的问题AI 辅助写作越来越常用可每个工具都要单独填 API Key、单独配模型地址写文档时切来切去很烦。所以我后来用 TaoToken 做统一 Key 管理把写作工具和 mdbook 构建流程串起来。这篇就按“装工具 → 配 Key → 写配置 → 构建验证 → 排错”的顺序把整套流程讲清楚你照着做就能跑通。2. TaoToken 前置准备统一 Key 怎么拿、怎么用在进入 mdbook 配置之前先把 Key 这件事解决掉。TaoToken 的作用是提供一个统一的 API 入口让你在多个 AI 写作/编码工具里复用同一套 Key而不用每个工具都去单独申请和管理。对写书场景来说这意味着你在编辑器里让 AI 帮你润色章节、补全示例代码时走的是同一个入口。第一步是拿到 Key。访问官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册登录后进入控制台。控制台地址是 https://taotoken.net/console 在这里可以创建和管理你的 API Key。创建完成后去 API Keys 页面 https://taotoken.net/api-keys 复制你的 Key注意它通常只完整显示一次先存到安全的地方。第二步是确认 API 入口。TaoToken 的 API 基础地址是 https://taotoken.net/api 注意这个地址不带任何查询参数。后面在工具配置里填的base_url就是它很多工具要求填到/v1这一层具体看工具文档但根地址认准这个。注意Key 属于敏感凭证不要写进会提交到 Git 的book.toml或任何公开文件里。建议放在本地环境变量或工具的私有配置文件中。如果你只是想先验证 Key 能不能用可以直接用模型对话页面 https://taotoken.net/model-chat 发一条消息测试确认返回正常再往下走。这一步能省掉后面很多“到底是 Key 错还是配置错”的排查时间。3. 安装 mdbook 并生成第一本书的骨架mdbook 是 Rust 写的最省事的安装方式是通过 Cargo。如果你还没装 Rust 工具链先去官网按提示装好rustup然后执行cargo install mdbook装完后验证一下版本确认命令可用mdbook --version接下来初始化一本书。找一个空目录执行mdbook init my-book cd my-book执行init时它会问你几个问题比如是否创建.gitignore、是否生成示例章节按需选择即可。初始化完成后目录结构大致是这样my-book/ ├── book.toml ├── src/ │ ├── SUMMARY.md │ └── chapter_1.mdbook.toml是全书配置src/SUMMARY.md是章节目录src/下放各个 Markdown 文件。这个结构就是 mdbook 的全部核心理解这两点后面就顺了。4. 可复制的 book.toml 骨架与 settings.json 配置先给一份我实际在用的book.toml骨架你可以直接复制后按需改[book] title 我的技术书 authors [你的名字] description 用 mdbook 构建的 Markdown 书籍 language zh-CN src src [build] build-dir book create-missing true [output.html] default-theme light preferred-dark-theme navy git-repository-url https://github.com/yourname/your-repo edit-url-template https://github.com/yourname/your-repo/edit/main/{path} [output.html.search] enable true几个参数说明一下src指向 Markdown 源目录build-dir是构建产物目录create-missing true表示SUMMARY.md里列了但文件不存在时自动创建写书时很省事。output.html.search打开后构建出的书自带搜索框。然后是 AI 写作工具的配置。很多编辑器类工具用settings.json管理模型接入下面是一个通用片段把 Key 和入口换成你自己的{ ai.provider: openai-compatible, ai.baseUrl: https://taotoken.net/api, ai.apiKey: 你的_TaoToken_Key, ai.model: claude-sonnet-4-20250514, ai.temperature: 0.3 }这里baseUrl填 TaoToken 的 API 根地址apiKey填你在 API Keys 页面拿到的 Key。不同工具字段名可能略有差异比如有的叫endpoint、有的叫apiBase认准“基础地址 Key”这两个核心项即可。温度调低一点0.3 左右更适合写技术文档输出更稳。提示如果你用的是 Claude Code 这类编码代理工具接入方式略有不同可以参考 https://taotoken.net/claude-code-anthropic 的说明长期做编码和 Agent 任务的话Coding Plan 页面 https://taotoken.net/coding-plan 有更合适的方案。5. 构建与本地预览验证build 和 serve 都要跑配置写好后先跑构建确认没有语法或结构错误mdbook build成功的话终端不会有报错当前目录下会多出一个book/文件夹里面是完整的静态 HTML。如果SUMMARY.md里引用了不存在的文件而你又没开create-missing这一步就会报错正好用来检查章节结构。接着启动本地预览服务mdbook serve --open--open会自动打开浏览器默认地址是http://localhost:3000。serve的好处是带热重载你改完 Markdown 保存浏览器会自动刷新写书体验很顺。这里有个我踩过的坑serve用的是内存里的实时构建而build是落盘产物两者理论上一致但如果你改了book.toml里的输出配置最好停掉serve重新跑一次避免看到旧配置的效果。验证“本地预览与构建产物一致”的方法很简单先mdbook build然后用任意静态服务器指向book/目录比如python3 -m http.server 8080 --directory book打开http://localhost:8080对比serve下的页面。如果搜索、主题切换、章节跳转都正常说明产物没问题可以直接部署了。6. 本篇常见错误排查报错一mdbook: command not found。说明 Cargo 的 bin 目录不在 PATH 里。Rust 默认装在~/.cargo/bin把它加进环境变量或者重新打开终端再试。报错二SUMMARY.md里的链接 404。检查文件名大小写Linux 下大小写敏感Chapter_1.md和chapter_1.md是两个文件。另外确认路径是相对src/的。报错三AI 工具返回 401 或鉴权失败。大概率是 Key 填错或baseUrl写成了带路径的地址。确认baseUrl是https://taotoken.net/apiKey 没有多余空格。可以先去模型对话页面发一条消息排除 Key 本身的问题。报错四serve端口被占用。默认 3000 端口常被其他前端项目占用用mdbook serve -p 3001换端口即可。报错五构建产物里搜索不工作。检查book.toml里[output.html.search]的enable是否为true改完必须重新buildserve的热重载不一定覆盖配置变更。7. 把写作和构建串成一条顺手的流水线整套流程跑下来我的实际用法是这样的mdbook 负责结构和发布TaoToken 统一 Key 负责让 AI 写作工具随时可用。写新章节时先在SUMMARY.md里加一行靠create-missing自动生成文件然后在编辑器里让 AI 帮忙补内容保存后serve自动刷新看效果定稿前跑一次build确认产物。如果你后面要长期用 AI 辅助编码和文档生成建议把 Key 管理集中到 TaoToken 控制台 https://taotoken.net/console 统一维护接入细节看文档 https://taotoken.net/doc 需要新建或轮换 Key 就去 https://taotoken.net/api-keys 。这样无论换哪个写作工具配置都只是改一个baseUrl加一个 Key 的事不用重复折腾。