Docsbook
概览

管理文档

了解如何在创建站点后使用文档。

Float Widget — Managing Your Site#

当你登录并查看你自己的网站时，一个管理小部件会出现在右下角。

┌──────────────────────┐
│ 👤 Your Name         │
│                      │
│ ✨ Premium / Free    │
│                      │
│ ⚙️ Settings          │
│ 🚪 Sign Out          │
└──────────────────────┘

点击头像或设置#

将打开一个包含管理选项的菜单。

您可以配置什么?#

1. 基本设置#

  • 工作区名称 — 显示在您的个人资料中
  • 订阅状态 — 免费或高级
  • 站点语言 — 默认语言

2. 域名#

(仅限高级版)

  • 如果您有自定义域名 — 请在此处指定
  • 而不是 docsbook.io/user/repo 您将拥有 docs.example.com

详细了解：自定义域名设置

3. 外观#

显示选项：

  • 隐藏“Powered by Docsbook” (高级版)

    • 移除页面底部的徽章
    • 使站点完全属于您

  • 主题 (即将推出)

    • 浅色 / 深色主题
    • 将在未来添加

4. 语言与翻译#

(Premium only)

  • 启用自动翻译
  • 选择语言
  • 文档自动翻译

详细了解：文档翻译

5. Dangerous Actions#

⚠️ 删除工作区

点击“删除工作区”以：

  • 删除所有设置
  • 禁用文档站点
  • 此操作不可撤销！

您的 GitHub 仓库不会被删除，只有文档站点。

如何更新文档?#

方法 1：GitHub Web 界面#

  1. 在 github.com 上打开您的仓库
  2. 编辑一个 markdown 文件
  3. 点击“提交更改”
  4. 更新将出现在您的 Docsbook 站点上

方法 2：本地 Git#

# 1. Clone the repository
git clone https://github.com/username/repo.git
cd repo
 
# 2. Edit files
nano docs/getting-started.md
 
# 3. Stage changes
git add docs/
 
# 4. Make a commit
git commit -m "Update documentation"
 
# 5. Push to GitHub
git push origin main

更新将自动显示在网站上！

方法 3：添加新页面#

  1. 在您的仓库中创建一个新的 .md 文件
  2. 编写内容
  3. 提交
  4. 文件出现在站点菜单中

示例：

# Create new file
echo "# API Reference" > docs/api/reference.md
 
# Add content
echo "Your API documentation..." >> docs/api/reference.md
 
# Commit
git add docs/api/reference.md
git commit -m "Add API reference"
git push origin main

方法 4：删除页面#

  1. 从 GitHub 仓库中删除文件
  2. 提交删除
  3. 页面从网站上消失

检查同步#

为什么我的网站没有更新?#

更新不是即时的，请检查：

  1. 验证 GitHub 上的提交

    • 打开 github.com → 你的仓库
    • 你看到新的提交了吗？
    • 如果看不到 — 请本地更新

  2. 刷新页面

    • 按下 Ctrl+F5 (或在 Mac 上按下 Cmd+Shift+R)
    • 这会清除浏览器缓存

  3. 等待 1-2 分钟

    • 同步不是即时的
    • Docsbook 定期检查 GitHub

  4. 检查互联网

    • 确保你有互联网连接
    • 检查仓库是否已打开

同步问题?#

文件未出现在菜单中:

  • 确保文件是 .md
  • 检查名称 — 仅限拉丁字母、数字和连字符

某些文件已更新，而其他文件未更新:

  • 可能是浏览器缓存
  • 使用 Ctrl+F5 清除缓存

到处都是旧版本:

  • 等待 5 分钟
  • 清除浏览器缓存

文档结构化#

如何组织文件？#

侧边栏是从文件夹结构构建的。 逻辑组织：

选项 1：按类别

docs/
├── README.md
├── getting-started.md
├── api/
│   ├── overview.md
│   ├── auth.md
│   └── endpoints.md
└── guides/
    ├── deployment.md
    └── troubleshooting.md

选项 2：按详细程度

docs/
├── README.md
├── 1-basics.md
├── 2-intermediate.md
├── 3-advanced.md
└── faq.md

我们推荐选项 1 — 更清晰的结构。

[See API](/zh/docs/guides/getting-started/api/overview)
[Start here](/zh/docs/guides/getting-started/getting-started)
[FAQ](/zh/docs/guides/faq)

这些链接会自动转换为正确的站点页面链接。

[Go to installation](#installation)

要使这起作用，文件中的另一部分必须具有此标题：

## Installation
 
Installation instructions...

图像 & 多媒体#

如何添加图片？#

  1. 将图片添加到文件夹 (例如，docs/images/screenshot.png)
  2. 上传到 GitHub
  3. 在 Markdown 中引用：
![Description](https://raw.githubusercontent.com/docsbook-io/docs/main/guides/getting-started/images/screenshot.png)

在哪里存储图像？#

创建文件夹：

docs/
├── README.md
├── images/
│   ├── screenshot.png
│   ├── architecture.jpg
│   └── diagram.gif
└── guides/

格式#

支持的：

  • PNG (最佳)
  • JPG (用于照片)
  • GIF (动画)
  • WebP (现代格式)

谁能看到我的文档?#

开放访问#

您的文档站点对所有人开放——即使仓库是私有的。

谁能看到它：

  • ✅ 互联网上的所有人
  • ✅ 搜索引擎机器人 (Google, Bing)
  • ✅ 没有 GitHub 帐户的人

这很好——您的文档随处可见！

仅您可见的设置#

当您登录时，管理小部件仅对您可见。

其他人只能看到：

  • 您的文档站点
  • 精美的设计
  • 内容
  • 他们看不到：控制按钮、设置、选项

协作文档#

如何协同工作？#

如果多人共同编写文档：

  1. 将他们添加到 GitHub 仓库 — 他们可以编辑
  2. 任何人都可以更新文档 — 通过提交拉取请求
  3. Docsbook 会自动更新网站 — 只要更改合并到主分支

工作流程#

Colleague 1         Colleague 2         Docsbook Site
    ↓                   ↓                    ↓
Edits          →   Pull Request    →   Updates
Documentation      (Code Review)       Automatically

文档版本控制#

⚠️ 尚未支持，但计划中。

目前仅存储最新版本。

如果您需要不同的版本：

  • 使用 Git 分支 (docs/v1, docs/v2)
  • 或者创建单独的仓库

分析#

我如何知道谁在阅读我的文档?#

(Will be built-in soon)

For now you can:

  1. Set up Google Analytics
  2. 跟踪您的域名流量
  3. See which pages are popular

Contact support@docsbook.io for setup help.

下一步骤#

由...提供支持 Docsbook