# 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]

<!-- 引用子目录的图片 -->
![地图](./maps/city-map.png)

<!-- 引用上级目录的文件 -->
: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
```