docs: 完善中文 README 文档

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-27 18:11:48 +08:00
parent 776e5b8f04
commit f63af18894
1 changed files with 69 additions and 1 deletions
@@ -1 +1,69 @@
-Slide
+# Slide
+
+基于 [Slidev](https://sli.dev/) 的多演示文稿项目，通过 Gitea Actions 实现 Docker 自动部署。
+
+## 快速开始
+
+```bash
+pnpm install
+pnpm run dev          # 启动开发服务器 http://localhost:3030
+```
+
+## 项目结构
+
+```
+index.html              # 首页（列出所有演示文稿）
+decks/
+  <deck-name>/
+    slides.md             # 幻灯片入口
+    pages/                # 额外幻灯片文件（通过 src: ./pages/xxx.md 导入）
+    public/               # 静态资源（图片、字体）
+scripts/
+  build.sh                # 构建所有演示文稿
+.gitea/workflows/         # CI/CD 流水线
+dist/                     # 构建产物（已 gitignore）
+```
+
+## 现有演示文稿
+
+| 演示文稿 | 开发命令 | 构建命令 |
+|----------|---------|---------|
+| demo | `pnpm run dev:demo` | `pnpm run build:demo` |
+| showcase | `pnpm run dev:showcase` | `pnpm run build:showcase` |
+
+## 命令
+
+```bash
+pnpm run dev           # 开发模式（默认加载 demo 演示文稿）
+pnpm run dev:<deck>    # 开发模式（加载指定演示文稿）
+pnpm run build         # 构建所有演示文稿 → dist/
+pnpm run build:<deck>  # 构建单个演示文稿
+pnpm run serve         # 构建并在 http://localhost:3030 提供服务
+pnpm run export        # 导出为 PDF（需要 playwright-chromium）
+```
+
+## 添加新演示文稿
+
+1. 创建目录：`decks/<name>/`
+2. 添加 `decks/<name>/slides.md`，写入 Slidev frontmatter
+3. （可选）添加 `pages/` 和 `public/` 子目录
+4. 在 `index.html` 的 `decks` 数组中注册名称
+5. 在 `package.json` 中添加 `dev:<name>` 和 `build:<name>` 脚本
+
+## CI/CD
+
+推送到 `main` 分支将触发 [Gitea Actions 流水线](.gitea/workflows/deploy.yaml)：
+
+1. 拉取代码
+2. 安装依赖（`pnpm install`）
+3. 构建所有演示文稿（`pnpm run build`）
+4. 将 `dist/` 部署到 nginx 容器，对外端口 **8080**
+
+运行器为自托管的 Gitea Act Runner（`aliyun` 标签），使用 Docker 模式。
+
+## 技术栈
+
+- [Slidev](https://sli.dev/) — 基于 Markdown 的幻灯片框架
+- [pnpm](https://pnpm.io/) — 包管理器
+- Nginx — 生产环境服务
+- Gitea Actions — CI/CD