ttrpg-tools/docs/cli.md

CLI 使用说明

TTRPG Tools 提供一个 CLI 工具，用于将目录内的各种 TTRPG 文档编译为 HTML。

安装

# 克隆仓库后安装依赖
npm install

# 全局链接 CLI 工具
npm link

安装完成后，可在任意目录使用 ttrpg 命令。

命令

CLI 使用子命令组织：

serve - 预览模式

运行一个 Web 服务器预览目录中的内容，并实时监听文件更新。

ttrpg serve [dir] -p 3000

参数：

参数	说明	默认值
[dir]	要预览的目录	. (当前目录)

选项：

选项	说明	默认值
-p, --port <port>	端口号	3000
-h, --host <host>	主机地址	0.0.0.0

功能：

• 扫描目录下的所有 .md、.csv、.yarn 文件
• 为每个文件创建路由
• 提供实时文件监听，修改后自动刷新
• 通过 /__CONTENT_INDEX.json 提供文件索引

示例：

# 预览当前目录
ttrpg serve

# 预览指定目录
ttrpg serve ./my-ttrpg-content

# 指定端口
ttrpg serve ./docs -p 8080

compile - 编译模式

将目录中的内容输出为带 hash 路由、单个 HTML 入口的 Web 应用。

ttrpg compile [dir] -o ./dist/output

参数：

参数	说明	默认值
[dir]	要编译的目录	. (当前目录)

选项：

选项	说明	默认值
-o, --output <dir>	输出目录	./dist/output

功能：

• 扫描目录下的所有 .md 文件
• 解析 Markdown 并生成路由
• 打包为带 hash 路由的单个 HTML 入口
• 复制引用的资源文件（图片、CSV 等）

示例：

# 编译当前目录
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 会在打包时自动处理这些引用：

<!-- 引用同目录下的 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
• 支持浏览器前进/后退

常见问题

端口被占用

# 使用其他端口
ttrpg serve -p 8080

编译输出为空

检查输入目录是否包含 .md 文件：

# 查看目录内容
ls -R ./content

# 重新编译
ttrpg compile ./content -o ./dist/output