179 lines
3.5 KiB
Markdown
179 lines
3.5 KiB
Markdown
# 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` |
|
||
| `-h, --host <host>` | 主机地址 | `0.0.0.0` |
|
||
|
||
**功能：**
|
||
|
||
- 扫描目录下的所有 `.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
|
||
```
|