diff --git a/.nojekyll b/.nojekyll
new file mode 100644
index 0000000..e69de29
diff --git a/CHANGELOG.md b/CHANGELOG.md
index cece813..4f17965 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,7 @@
- Markdown 与内嵌按钮一等支持：`post_group_message`/`post_c2c_message` 新增 `markdown`/`keyboard` 参数（自动置 msg_type=2，与 content 互斥）；新增 `respond_interaction()` 回应按钮回调；`Interaction` payload 补齐 `chat_type`/`scene`/`group_openid` 等官方字段
- `Event` 新增 `event_id` 属性（推送信封顶层的事件 id，与 op/t/d 平级）：非消息事件（GROUP_ADD_ROBOT 等）的被动回复不再需要手动 `event.raw["id"]`
- 按钮快捷构造与点击处理：`button()`/`keyboard()` 生成内嵌按钮（免手写嵌套 dict）；`Interaction` 新增 `button_data` 属性（被点按钮的 action.data）；examples/group_bot 补 `/btn` 卡片与 `INTERACTION_CREATE` 回调示例
+- 文档站点：基于 docsify（侧边栏、全文搜索、代码复制、mermaid 图渲染、分页），`npx docsify-cli serve` 本地预览；新增 `examples/README.md` 示例索引
### 变更
diff --git a/README.md b/README.md
index f4feea1..d4763bf 100644
--- a/README.md
+++ b/README.md
@@ -126,6 +126,12 @@ uv run pytest # 单元测试
uv run ruff check src tests examples && uv run pyright
```
+文档站点基于 [docsify](https://docsify.js.org/)（无需构建，仓库根 `index.html` + Markdown），本地预览：
+
+```bash
+npx docsify-cli serve # 打开 http://localhost:3000
+```
+
## 待完善
- 更多 OpenAPI 封装（按需在 `api.py` 的 `BotApi` 上加薄封装即可）
diff --git a/_sidebar.md b/_sidebar.md
new file mode 100644
index 0000000..e5949c3
--- /dev/null
+++ b/_sidebar.md
@@ -0,0 +1,6 @@
+- [首页](/README.md)
+- [使用指南](/docs/GUIDE.md)
+- [API 参考](/docs/API.md)
+- [架构设计](/docs/ARCHITECTURE.md)
+- [示例](/examples/README.md)
+- [更新日志](/CHANGELOG.md)
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..b60acd6
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,25 @@
+# 示例
+
+可运行的完整示例，均以仓库根目录为工作目录启动（`.env`、`intents.toml` 放在根目录）。
+
+| 示例 | 接入方式 | 内容 |
+|---|---|---|
+| `group_bot/main.py` | WebSocket | @消息被动回复、`/img` 富媒体图片、`/btn` Markdown 按钮卡片与点击回调、入群欢迎、单聊回复 |
+| `webhook_bot/main.py` | Webhook | HTTP 回调收群 @消息并被动回复的最小接入 |
+
+## 运行前提
+
+1. 根目录 `.env` 配好 `APPID`/`APPSECRET`（`webhook_bot` 需另设 `CONNECTER=webhook`）；
+2. `intents.toml` 开启对应事件分组（`group_bot` 需 `GROUP_AND_C2C_EVENT` 与 `INTERACTION`，`webhook_bot` 需 `GROUP_AND_C2C_EVENT`）；
+3. `group_bot` 要求机器人已开通群聊能力并拉入测试群；`webhook_bot` 要求公网 HTTPS 部署（平台仅支持 80/443/8080/8443 端口，本地调试可用内网穿透）。
+
+## 运行
+
+```bash
+uv run python examples/group_bot/main.py
+uv run python examples/webhook_bot/main.py
+```
+
+Webhook 示例启动后，把 `https://<你的域名>:<端口>/qqbot/webhook` 填到开放平台回调地址；保存时平台先发 op=13 验证请求，SDK 自动完成签名应答。
+
+接入方式切换与 handler 写法详见 [使用指南](docs/GUIDE.md#接入方式选择)。
diff --git a/index.html b/index.html
new file mode 100644
index 0000000..70db2d1
--- /dev/null
+++ b/index.html
@@ -0,0 +1,88 @@
+
+
+
+
+ qqbotsdk 文档
+
+
+
+
+
+
+
+ 加载中…
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+