Docsbook
概览

将你的 README.md 变成真正的文档网站

你的项目文档位于 README.md 中。你一直打算搭建一个真正的文档网站。你看过 Docusaurus，打开了配置指南，然后关掉了标签页。

这篇文章提供了一个 5 秒替代方案。

简而言之#

  • 大多数开源软件项目仅以 README.md 发布文档
  • README 当然可以，但与真正的文档网站相比，它在 Google 中的索引效果较差，也没有 AI 聊天、分析功能和翻译
  • Docsbook 可在 5 秒内将 README.md（以及可选的 docs/）转换为位于 docsbook.io/yourorg/yourrepo 的网站
  • 发布公共仓库无需任何费用。无需 CI/CD，也无需配置文件。

为什么 README 不够#

仅使用 README 的项目会面临三种损失：

1. SEO#

GitHub README 会被索引，但 Google 会针对仓库名称为 github.com/user/repo 排名，而不会针对技术查询进行排名。搜索“如何使用 X 库进行身份验证”的用户很少会访问 README，即使答案就在其中。

位于 docs.yourproject.com（或 docsbook.io/yourorg/yourrepo）的真正文档网站可以针对 README 涵盖但无法展现的长尾查询获得排名。

2. AI 分发#

ChatGPT 和 Perplexity 确实会引用 GitHub README，但并不一致。包含 llms.txt、结构化标题和 JSON-LD 的整洁文档网站被引用的频率要高得多。

如果您的项目依赖开发者发现，那么 AI 引用现在已经是一个真实的渠道——请参阅如何让 ChatGPT 引用文档。

3. UX#

一份 1,500 行的 README 就像一面需要不断滚动的长墙。文档站点则提供侧边栏、搜索功能、作为锚点链接的标题、面包屑导航以及复制代码按钮。内容相同，但可发现性大大提升。

5 秒设置#

三个步骤：

  1. 访问 docsbook.io
  2. 使用 GitHub 登录
  3. 粘贴 github.com/yourorg/yourrepo

网站已上线于 docsbook.io/yourorg/yourrepo。您的 README 将显示为主页。如果您有一个 docs/ 文件夹，其中的页面将成为侧边栏。

无需配置。无需 docsbook.config.js。无需 CI/CD 流水线。无需部署。

哪些内容会被索引#

Docsbook 会读取：

  • 仓库根目录中的 README.md → 主页
  • docs/ 文件夹（递归读取）→ 网站页面
  • docs/README.md → 文档落地页
  • YAML frontmatter（title、description）→ 页面元数据

如果你只有一个 README，就会得到一个单页文档网站。如果你有 docs/getting-started.md、docs/api.md 等文件，就会得到一个多页面网站，其侧边栏根据文件夹结构构建。

Frontmatter（可选）#

在任何 Markdown 文件顶部添加 YAML：

---
title: "Quick Start"
description: "Get up and running in 60 seconds"
---
 
# Quick Start
...

title 会成为搜索引擎中的页面标题。description 会成为元描述。如果两者都跳过，Docsbook 会使用第一个 H1 作为标题，并使用第一段作为描述。

发布开源项目需要多少费用？#

发布网站无需费用，阅读网站也无需费用。按量计费的是 AI 使用量：每个项目都有自己的余额，向助手提问和运行翻译都会消耗余额。当前价格可在 docsbook.io/pricing 上查看，每次请求都会根据实时价格常量生成。

发布一个代码仓库后，你将获得：

  • 任何公开的 GitHub 代码仓库，并将其渲染为网站
  • 自定义网站名称、图标、徽标，以及浅色和深色模式的强调色
  • 主题切换、搜索、面包屑导航、复制代码按钮
  • 页眉链接和社交链接（GitHub、Discord、X）
  • 分析数据——页面浏览量、热门页面、引荐来源、国家/地区
  • llms.txt 和 llms-full.txt，帮助 AI 发现内容
  • MCP 服务器，让 Claude Code 和 Cursor 能够读取和编辑文档
  • 由你的 README.md 和 docs/ 提供支持的 AI 聊天
  • docs.yourproject.com，自动配置 SSL

唯一无法关闭的是页面页脚中小小的“Powered by Docsbook”链接。它会无条件地显示在每个 Docsbook 网站上——这就是无需自行运行托管服务所要付出的代价。

如何使用我自己的域名代替 docsbook.io？#

将子域名指向 Docsbook，它会在该域名下提供您的文档，并自动配置 SSL。

  • 控制面板 → 设置 → 域名
  • DNS：CNAME docs → cname.vercel-dns.com
  • SSL 会自动配置

完整操作指南，包括顶级域名和重定向：文档自定义域名。

推送时会发生什么#

你将提交推送到 main。Docsbook 会为更改建立索引并更新网站。无需 GitHub Action，也无需构建步骤。新内容会在几秒内上线。

常见问题#

它适用于私有仓库吗？#

可以。Docsbook 通过您的 GitHub OAuth 权限范围进行身份验证，发布的网站本身可以是公开的，也可以是私有的。

MDX 或交互式演示呢？#

Docsbook 以 Markdown 为先。对于交互式演示，请将演示托管在其他位置并链接到它。如果你的项目需要在文档页面中嵌入 React 组件，请参阅2026 年是否应该弃用 Docusaurus？——Docusaurus 更适合这种场景。

它看起来会和其他 Docsbook 网站完全一样吗？#

您可以控制品牌颜色、字体、布局、页眉、页脚、侧边栏以及自己的域名。唯一无法移除的是页脚中的小型“由 Docsbook 提供支持”链接——它会显示在每个 Docsbook 网站上。

以后可以迁移吗？#

可以。您的文件位于 GitHub。取消订阅，将 DNS 指向其他位置，您的内容不会受到影响。

粘贴 github.com/yourorg/yourrepo，网站五秒内即可上线。不会有任何内容被复制到您的代码库之外，因此 README 始终是唯一事实来源。

免费开始 — 无需信用卡

后续步骤#

此页面对您有帮助吗？

由...提供支持 Docsbook