Docsbook
概览

创建文档站点

本指南将引导您在 Docsbook 上设置您的第一个文档站点——无需任何编码经验。每个步骤都包含截图，因此您始终知道要点击哪里。

您需要什么#

开始之前，请确保您拥有：

  • 一台具有互联网连接的计算机 — 任何操作系统都可以 (Windows, Mac, Linux)
  • 一个免费的 GitHub 帐户 — 您的文档文件将存储在此处

如果您还没有 GitHub 帐户，请访问 github.com 并点击 注册 — 它是免费的，大约需要两分钟。

什么是 GitHub？ GitHub 是一个流行的网站，人们可以在这里存储和共享文件 — 特别是用于文档和软件项目。您可以把它想象成 Google Drive，但专门设计用于文本文件和代码。Docsbook 从 GitHub 读取您的文件，并将其转换为精美的文档网站。

步骤 1 — 创建一个 GitHub 帐户（如果您已经拥有一个，请跳过）#

  1. 访问 github.com
  2. 点击右上角的注册
  3. 输入您的电子邮件地址并选择一个密码
  4. 选择一个用户名 — 这将出现在您的文档 URL 中（例如，docsbook.io/your-username/your-repo）
  5. 验证您的电子邮件地址

Screenshot: GitHub homepage with Sign up button highlighted

步骤 2 — 为您的文档创建存储库#

什么是存储库？ 存储库（或“repo”）就像 GitHub 上的一个文件夹。它存储所有您的文档文件。您需要为每个文档站点创建一个存储库。

选项 A — 从示例开始（推荐给初学者）#

开始的最简单方法是复制我们的一个现成的示例仓库。这被称为 forking — 它创建你自己的个人仓库副本，你可以自由编辑。

  1. 前往 github.com/docsbook-io/docs

  2. 你将看到一个包含文件和描述的页面

    Screenshot: docsbook-io/docs repository page with Fork button visible in top-right

  3. 点击页面右上角的 Fork 按钮

    Fork 的含义是什么？ “Forking” 意味着创建别人的仓库的个人副本。就像在 Google 文档上点击“复制”一样。你的副本是完全独立的——你所做的更改不会影响原始文件。

  4. 出现一个对话框。保持所有设置不变，然后点击 Create fork

    Screenshot: Fork dialog with "Create fork" button highlighted

  5. 片刻之后，GitHub 会将你带到你的新仓库，位于 github.com/YOUR-USERNAME/docs

    Screenshot: Your newly forked repository page

完成！ 你现在拥有一个包含示例文档文件的仓库，可以随时编辑。

Option B — Start from Scratch#

如果您更喜欢从头开始：

  1. 确保您已登录 GitHub

  2. 前往 github.com/new

    Screenshot: GitHub new repository form

  3. 填写表单：

    • Repository name — 选择一个没有空格的简短名称，例如 my-docs 或 product-docs
    • Description — 可选，对该项目的简短描述
    • Visibility — 选择 Public (Docsbook 需要公共仓库)
    • 选中 Add a README file — 这将创建您的主页

  4. 点击 Create repository

    Screenshot: Create repository button highlighted

  5. 您的新仓库已打开。它包含一个文件：README.md

步骤 3 — 将您的仓库连接到 Docsbook#

现在您已经拥有了一个 GitHub 仓库，让我们将其连接到 Docsbook 以创建您的文档站点。

  1. 前往 docsbook.io/connect

    Screenshot: Docsbook connect page with Sign in button

  2. 点击 使用 GitHub 登录

  3. GitHub 会要求您授权 Docsbook。点击 授权 Docsbook

    Docsbook 仅读取您的仓库文件 — 它无法修改或删除任何内容。

  4. 您将看到您的仓库列表。找到您刚刚创建的仓库并点击它

    Screenshot: Repository list on Docsbook connect page with a repo highlighted

  5. Docsbook 将创建您的文档站点。您将自动重定向到它。

您的文档站点现在已上线：

docsbook.io/YOUR-GITHUB-USERNAME/YOUR-REPO-NAME

步骤 4 — 编辑您的文档#

有三种方法可以编辑您的文档文件。选择最适合您的一个。

选项 A — 在 GitHub 上直接编辑 (最简单，无需设置)#

这是最简单的方法。您可以在 GitHub 上的浏览器中直接编辑文件——无需安装任何软件。

编辑现有页面#

  1. 转到 GitHub 上的您的仓库 (例如：github.com/YOUR-USERNAME/docs)

  2. 单击要编辑的文件，例如 README.md

    Screenshot: Repository file list with README.md highlighted

  3. 单击文件内容右上角的铅笔图标 (✏️)

    Screenshot: File view with pencil/edit icon highlighted

  4. 文件将在编辑器中打开。进行更改。

    您的文档使用 Markdown——一种格式化文本的简单方法。例如：**bold** 变为 粗体，# Heading 变为一个大标题。有关更多信息，请参阅下面的 Markdown 指南。

    Screenshot: GitHub file editor with some text being typed

4.1 学习 如何编辑 Markdown 文件以进行漂亮的自定义

  1. 编辑完成后，向下滚动到 提交更改 部分

  2. 可选地，写一个简短的说明，描述您所做的更改 (例如：“更新介绍”)

  3. 单击 提交更改

    Screenshot: Commit changes form with green Commit button highlighted

  4. 返回您的 Docsbook 站点并刷新——您的更改会立即出现。

添加新页面#

  1. 转到 GitHub 上的您的仓库

  2. 单击 添加文件 → 创建新文件

    Screenshot: Add file dropdown with "Create new file" option highlighted

  3. 在 命名您的文件 字段中，键入路径和文件名。例如：guides/installation.md

    在名称中键入 / 会自动创建一个文件夹。例如，guides/installation.md 创建一个 guides 文件夹，其中包含 installation.md。

    Screenshot: New file name field with "guides/installation.md" typed

  4. 在下面的编辑器中编写您的内容

  5. 单击 提交新文件

    Screenshot: Commit new file button highlighted

新页面会自动出现在您的 Docsbook 侧边栏中。

删除页面#

  1. 在您的仓库中打开文件

  2. 单击文件内容右上角附近的 ⋯ (三个点) 菜单图标

    Screenshot: File view with three-dot menu highlighted

  3. 单击 删除文件

  4. 单击 提交更改 以确认

Option B — Edit with Claude Code (AI-assisted, no terminal needed)#

Claude Code 是一个 AI 编码助手，可以通过对话阅读、创建和编辑您的文档文件——无需终端命令或 Git 知识。如果您想快速生成大量内容，这非常有用。

Setup (one time)#

  1. 前往 claude.ai/code 并下载 Claude Code

  2. 按照屏幕上的说明进行安装

  3. 打开 Claude Code 并说：

    "将 github.com/YOUR-USERNAME/YOUR-REPO-NAME 的 GitHub 仓库克隆到我的电脑并打开它"

    Claude 会处理其余部分——无需终端。

Creating and editing documentation#

只需在聊天面板中描述您想要的内容：

创建新页面

"创建一个名为 guides/installation.md 的新文件，其中包含入门指南。包括系统要求、安装步骤和首次登录部分。"

编辑现有页面

"打开 guides/quick-start.md 并在末尾添加一个“故障排除”部分，其中包含 5 个常见问题和解决方案。"

重写或改进

"阅读 guides/quick-start.md 并使其更短更简单——面向没有技术背景的人。"

一次创建多个页面

"创建以下页面：guides/faq.md 包含 10 个账单问题，以及 api/overview.md 包含 REST API 概述。"

Claude 会编写内容并保存文件。查看结果并根据需要提出调整。

Screenshot: Claude Code chat with a request typed and the response being written into the file

Save and publish your changes#

完成后，只需告诉 Claude：

"提交所有更改并推送到 GitHub。"

Claude 会为您运行必要的命令。您的 Docsbook 站点将在几秒钟内更新。

连接您的文档#

之后，您应该连接仓库，前往 docsbook.io/connect — 此页面允许您随时使用 GitHub 登录并选择一个仓库。

Markdown Basics#

Docsbook 使用 Markdown — 一组简单的符号，用于控制文本的格式。以下是您需要了解的一切：

文本格式化#

你输入的内容 显示效果
**bold text** 粗体文本
*italic text* 斜体文本
~~strikethrough~~ 删除线
`inline code` inline code

标题#

# Large heading (page title)
## Medium heading (section)
### Small heading (sub-section)

Lists#

- First item
- Second item
  - Nested item (indent with 2 spaces)
 
1. First step
2. Second step
3. Third step
[Click here](https://example.com)
[Link to another page in your docs](/zh/docs/guides/getting-started/other-page)

图片#

![Description of image](https://raw.githubusercontent.com/docsbook-io/docs/main/guides/getting-started/images/my-screenshot.png)

代码块#

使用三个反引号来显示具有语法高亮的代码：

```javascript
console.log("Hello!")
```

Callout / Quote#

> This is a note or important callout.

您的文档站点结构#

Docsbook 会自动从您的文件和文件夹结构构建侧边栏导航。无需进行任何配置。

您的仓库中的文件 Docsbook 中的侧边栏
README.md 首页
installation.md 安装
guides/quick-start.md 指南 → 快速入门
api/overview.md API → 概览

提示：

  • 文件和文件夹名称会成为页面标题（连字符会被空格替换）
  • README.md 在一个文件夹中会成为该文件夹的索引页
  • 小写名称和连字符最适合 URL：getting-started.md → /getting-started

下一步骤#

由...提供支持 Docsbook