2026-03-16 13:52:56 +08:00
|
|
|
|
# CLI 使用说明
|
|
|
|
|
|
|
|
|
|
|
|
TTRPG Tools 提供一个 CLI 工具，用于将目录内的各种 TTRPG 文档编译为 HTML。
|
|
|
|
|
|
|
|
|
|
|
|
## 安装
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 克隆仓库后安装依赖
|
|
|
|
|
|
npm install
|
|
|
|
|
|
|
|
|
|
|
|
# 全局链接 CLI 工具
|
|
|
|
|
|
npm link
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
安装完成后，可在任意目录使用 `ttrpg` 命令。
|
|
|
|
|
|
|
|
|
|
|
|
## 命令
|
|
|
|
|
|
|
|
|
|
|
|
CLI 使用子命令组织：
|
|
|
|
|
|
|
|
|
|
|
|
### serve - 预览模式
|
|
|
|
|
|
|
|
|
|
|
|
运行一个 Web 服务器预览目录中的内容，并实时监听文件更新。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
ttrpg serve [dir] -p 3000
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**参数：**
|
|
|
|
|
|
|
|
|
|
|
|
| 参数 | 说明 | 默认值 |
|
|
|
|
|
|
|------|------|--------|
|
|
|
|
|
|
| `[dir]` | 要预览的目录 | `.` (当前目录) |
|
|
|
|
|
|
|
|
|
|
|
|
**选项：**
|
|
|
|
|
|
|
|
|
|
|
|
| 选项 | 说明 | 默认值 |
|
|
|
|
|
|
|------|------|--------|
|
|
|
|
|
|
| `-p, --port <port>` | 端口号 | `3000` |
|
2026-03-26 11:24:28 +08:00
|
|
|
|
| `-h, --host <host>` | 主机地址 | `0.0.0.0` |
|
2026-03-16 13:52:56 +08:00
|
|
|
|
|
|
|
|
|
|
**功能：**
|
|
|
|
|
|
|
|
|
|
|
|
- 扫描目录下的所有 `.md`、`.csv`、`.yarn` 文件
|
|
|
|
|
|
- 为每个文件创建路由
|
|
|
|
|
|
- 提供实时文件监听，修改后自动刷新
|
|
|
|
|
|
- 通过 `/__CONTENT_INDEX.json` 提供文件索引
|
|
|
|
|
|
|
|
|
|
|
|
**示例：**
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 预览当前目录
|
|
|
|
|
|
ttrpg serve
|
|
|
|
|
|
|
|
|
|
|
|
# 预览指定目录
|
|
|
|
|
|
ttrpg serve ./my-ttrpg-content
|
|
|
|
|
|
|
|
|
|
|
|
# 指定端口
|
|
|
|
|
|
ttrpg serve ./docs -p 8080
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### compile - 编译模式
|
|
|
|
|
|
|
|
|
|
|
|
将目录中的内容输出为带 hash 路由、单个 HTML 入口的 Web 应用。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
ttrpg compile [dir] -o ./dist/output
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
**参数：**
|
|
|
|
|
|
|
|
|
|
|
|
| 参数 | 说明 | 默认值 |
|
|
|
|
|
|
|------|------|--------|
|
|
|
|
|
|
| `[dir]` | 要编译的目录 | `.` (当前目录) |
|
|
|
|
|
|
|
|
|
|
|
|
**选项：**
|
|
|
|
|
|
|
|
|
|
|
|
| 选项 | 说明 | 默认值 |
|
|
|
|
|
|
|------|------|--------|
|
|
|
|
|
|
| `-o, --output <dir>` | 输出目录 | `./dist/output` |
|
|
|
|
|
|
|
|
|
|
|
|
**功能：**
|
|
|
|
|
|
|
|
|
|
|
|
- 扫描目录下的所有 `.md` 文件
|
|
|
|
|
|
- 解析 Markdown 并生成路由
|
|
|
|
|
|
- 打包为带 hash 路由的单个 HTML 入口
|
|
|
|
|
|
- 复制引用的资源文件（图片、CSV 等）
|
|
|
|
|
|
|
|
|
|
|
|
**示例：**
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 编译当前目录
|
|
|
|
|
|
ttrpg compile
|
|
|
|
|
|
|
|
|
|
|
|
# 编译指定目录并输出到指定位置
|
|
|
|
|
|
ttrpg compile ./content -o ./build
|
|
|
|
|
|
|
|
|
|
|
|
# 编译并部署
|
|
|
|
|
|
ttrpg compile ./docs -o ./public && npm run preview
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 输入文件
|
|
|
|
|
|
|
|
|
|
|
|
CLI 会搜索目录下的以下文件：
|
|
|
|
|
|
|
|
|
|
|
|
- `.md` - Markdown 文档
|
|
|
|
|
|
- `.csv` - 表格数据
|
|
|
|
|
|
- `.yarn` - Yarn Spinner 叙事文件
|
|
|
|
|
|
|
|
|
|
|
|
### 文件组织建议
|
|
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
my-ttrpg-content/
|
|
|
|
|
|
├── index.md # 首页
|
|
|
|
|
|
├── rules/
|
|
|
|
|
|
│ ├── index.md # 规则首页
|
|
|
|
|
|
│ ├── combat.md # 战斗规则
|
|
|
|
|
|
│ └── magic.md # 魔法系统
|
|
|
|
|
|
├── characters/
|
|
|
|
|
|
│ ├── index.md
|
|
|
|
|
|
│ └── npc-list.csv # NPC 列表
|
|
|
|
|
|
└── assets/
|
|
|
|
|
|
├── images/ # 图片资源
|
|
|
|
|
|
└── icons/ # 图标资源
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### 相对路径引用
|
|
|
|
|
|
|
|
|
|
|
|
若 Markdown 文件通过相对路径引用了其他文件（如图片、CSV），CLI 会在打包时自动处理这些引用：
|
|
|
|
|
|
|
|
|
|
|
|
```markdown
|
|
|
|
|
|
<!-- 引用同目录下的 CSV -->
|
|
|
|
|
|
:table[./sparks.csv]
|
|
|
|
|
|
|
|
|
|
|
|
<!-- 引用子目录的图片 -->
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- 引用上级目录的文件 -->
|
|
|
|
|
|
:deck[../data/cards.csv]
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 开发服务器特性
|
|
|
|
|
|
|
|
|
|
|
|
### 实时索引
|
|
|
|
|
|
|
|
|
|
|
|
访问 `http://localhost:3000/__CONTENT_INDEX.json` 可获取当前内容目录的文件索引。
|
|
|
|
|
|
|
|
|
|
|
|
### 自动刷新
|
|
|
|
|
|
|
|
|
|
|
|
文件变化时，服务器会自动重新加载内容，无需手动刷新页面。
|
|
|
|
|
|
|
|
|
|
|
|
### SPA 路由
|
|
|
|
|
|
|
|
|
|
|
|
使用 hash 路由支持单页应用导航：
|
|
|
|
|
|
|
|
|
|
|
|
- `/content/rules/combat.md` → `#/content/rules/combat.md`
|
|
|
|
|
|
- 支持浏览器前进/后退
|
|
|
|
|
|
|
|
|
|
|
|
## 常见问题
|
|
|
|
|
|
|
|
|
|
|
|
### 端口被占用
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 使用其他端口
|
|
|
|
|
|
ttrpg serve -p 8080
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### 编译输出为空
|
|
|
|
|
|
|
|
|
|
|
|
检查输入目录是否包含 `.md` 文件：
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
# 查看目录内容
|
|
|
|
|
|
ls -R ./content
|
|
|
|
|
|
|
|
|
|
|
|
# 重新编译
|
|
|
|
|
|
ttrpg compile ./content -o ./dist/output
|
|
|
|
|
|
```
|
