创建您的第一个文档网站

在本教程中，您将从 GitHub 仓库发布一个文档网站，并修改其中的一个页面。您无需任何编码经验，也无需安装任何软件：每个步骤都在浏览器中完成。

最终您将拥有：一个位于 docsbook.io/YOUR-USERNAME/docs 的在线文档网站，以及其中一个由您亲自编辑的页面。

开始之前#

你需要准备两样东西：

• 浏览器和互联网连接。任何操作系统都可以。
• GitHub 账户。它是免费的。如果你还没有账户，第 1 步会帮助你创建一个。

什么是 GitHub？GitHub 是一个人们存储和分享文本文件的网站。可以把它想象成专为文档和代码打造的 Google 云端硬盘。Docsbook 会从 GitHub 读取你的文件，并将其发布为文档网站。

第 1 步：创建 GitHub 账户#

如果您已有账户，请跳过此步骤。

1. 前往 github.com。
2. 点击右上角的 注册。
3. 输入您的电子邮件地址并设置密码。
4. 选择用户名。它会显示在您的文档 URL 中，例如 docsbook.io/your-username/your-repo。
5. 确认 GitHub 发送到您邮箱的验证码。

第 2 步：复刻示例仓库#

仓库（简称“repo”）是 GitHub 上用于存放文档文件的文件夹。一个仓库发布一个文档网站。

与其从空仓库开始，不如复制 Docsbook 示例仓库。复制他人的仓库称为复刻（fork），而你的副本是独立的：你所做的更改永远不会影响原始仓库。

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

   

2. 点击右上角的 Fork。

3. 保留所有设置不变，然后点击 Create fork。

   

4. GitHub 会在 github.com/YOUR-USERNAME/docs 打开你的新仓库。

   

现在你已经拥有了一个包含示例文档、可以随时发布的仓库。

第 3 步：将仓库连接到 Docsbook#

1. 前往 docsbook.io/connect。

   

2. 选择一种登录方式 — GitHub、Google、Apple 或通过电子邮件获取一次性代码 — 并完成登录。

3. 如果你使用 Google、Apple 或电子邮件登录，Docsbook 会请求访问 GitHub。点击 Authorize docsbook。

   Docsbook 会读取你的仓库文件。除非你要求，否则它无法修改或删除仓库中的任何内容。

4. 在列表中找到你复刻的仓库，然后点击它。

   

5. Docsbook 会构建你的网站并将你重定向到该网站。

你的文档现在已发布于：

docsbook.io/YOUR-GITHUB-USERNAME/docs

打开它并点击侧边栏中的链接。你看到的每个页面都是你复刻的仓库中的一个 markdown 文件。

第 4 步：在 GitHub 上编辑页面#

1. 在 github.com/YOUR-USERNAME/docs 打开您的仓库。

2. 点击要更改的文件——先从 README.md 开始。

   

3. 点击文件右上方附近的铅笔图标。

   

4. 修改一句话。该文件使用 Markdown 编写：**bold** 会渲染为粗体，# Heading 会渲染为大标题。本页末尾的 Markdown 语法参考介绍了其余语法。

   

5. 向下滚动到提交更改。

6. 写一条简短的备注，说明您更改了什么，例如“更新介绍”。

7. 点击提交更改。

   

步骤 5：查看网站上的更改#

返回您的 Docsbook 网站并重新加载您编辑的页面。您的新句子就在其中。

整个流程就是这样：提交到 GitHub，已发布的网站随之更新。您已完成本教程。

添加和删除页面#

添加页面的流程相同，只是使用不同的按钮。

添加页面：

1. 打开您的仓库，然后点击添加文件 → 创建新文件。

   

2. 在为文件命名中，输入路径和文件名，例如 guides/installation.md。输入 / 会创建文件夹。

   

3. 编写内容，然后点击提交新文件。

该页面会自动显示在 Docsbook 侧边栏中。

删除页面：

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

2. 点击右上方附近的⋯菜单。

   

3. 点击删除文件，然后点击提交更改。

其他实现方式#

上面的教程采用的是无需安装任何软件即可使用的方法。完成第一个站点后，还有三种替代方式可供选择。

不进行分叉，而是从空仓库开始。 前往 github.com/new，为仓库填写一个不含空格的简短名称，选择 Public，勾选 Add a README file，然后点击 Create repository。接着按照第 3 步中的方式连接即可。

使用 AI 编程助手编写页面。 Claude Code 可以通过对话读取、创建和编辑文件；当你一次要创建许多页面时，这样会更快。请从 claude.ai/code 安装它，让它克隆你的仓库，然后描述你的需求——“创建 guides/installation.md，包含需求、安装和首次登录部分”。完成后，让它提交并推送更改，网站就会更新。

直接在已发布的页面上编辑。 连接网站后，你可以在正在阅读的页面中，通过 Docsbook AI 聊天修改内容块，无需使用 GitHub，也无需安装任何软件。请参阅在实时页面上编辑。

参考：Markdown 语法#

Markdown 是一组用于控制格式的符号。以下是文档中使用的符号。

文本#

标题、列表和链接#

# Large heading (page title)
## Medium heading (section)
### Small heading (sub-section)
 
- First item
- Second item
  - Nested item, indented by two spaces
 
1. First step
2. Second step
 
[Link to an external site](https://example.com)
[Link to another page in your docs](/docsbook-io/docs/guides/getting-started/managing-docs)

图像和代码块#

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

使用三个反引号包围代码块并指定语言，以便进行语法高亮：

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

提示框#

> This is a note or an important callout.

参考：您的文件如何变成页面#

Docsbook 根据您的文件和文件夹名称构建侧边栏。无需进行任何配置。

由此可得出三条规则：

• 文件和文件夹名称会成为页面标题，其中的连字符会替换为空格。
• 文件夹中的 README.md 会成为该文件夹的索引页面。
• 带连字符的小写名称会生成易读的 URL：getting-started.md 会变成 /getting-started。

如需了解决定这些页面顺序的因素，请参阅管理您的文档站点。

后续步骤#

• 管理您的文档站点 — 更新内容、控制访问权限，以及修复未刷新的站点。
• 设置自定义域名 — 从 docs.yourcompany.com 提供文档。
• 启用全文搜索 — 让读者可以通过关键词查找页面。