docs: Document the tttk check command
Add check to the CLI guide, README, QWEN, and project structure: options, exit codes, diagnostic codes, and the checks not yet implemented. Mark compile as an unimplemented stub and fix stale element syntax in examples.
This commit is contained in:
+100
-27
@@ -1,6 +1,8 @@
|
||||
# CLI 使用说明
|
||||
|
||||
TTTK 提供一个 CLI 工具，用于将目录内的各种 TTRPG 文档编译为 HTML。
|
||||
TTTK 提供一个 CLI 工具，用于预览和校验目录内的 TTRPG 文档。
|
||||
|
||||
> 将内容编译为 HTML 的 `compile` 命令尚未实现（见下方说明）。
|
||||
|
||||
## 安装
|
||||
|
||||
@@ -59,46 +61,111 @@ tttk serve ./my-ttrpg-content
|
||||
tttk serve ./docs -p 8080
|
||||
```
|
||||
|
||||
### compile - 编译模式
|
||||
### check - 校验模式
|
||||
|
||||
将目录中的内容输出为带 hash 路由、单个 HTML 入口的 Web 应用。
|
||||
静态校验目录内的 tttk 文档，输出结构化诊断（文件、行号、代码），存在错误时以退出码 `1` 结束。
|
||||
|
||||
```bash
|
||||
tttk compile [dir] -o ./dist/output
|
||||
tttk check [dir] --json
|
||||
```
|
||||
|
||||
`lint` 是 `check` 的别名。
|
||||
|
||||
**参数：**
|
||||
|
||||
| 参数 | 说明 | 默认值 |
|
||||
|------|------|--------|
|
||||
| `[dir]` | 要编译的目录 | `.` (当前目录) |
|
||||
| `[dir]` | 要校验的目录 | `.` (当前目录) |
|
||||
|
||||
**选项：**
|
||||
|
||||
| 选项 | 说明 | 默认值 |
|
||||
|------|------|--------|
|
||||
| `-o, --output <dir>` | 输出目录 | `./dist/output` |
|
||||
| `--json` | 以 JSON 输出诊断 | `false` |
|
||||
| `--strict` | 将警告视为错误 | `false` |
|
||||
| `--quiet` | 只报告错误 | `false` |
|
||||
|
||||
**功能：**
|
||||
**退出码：**
|
||||
|
||||
- 扫描目录下的所有 `.md` 文件
|
||||
- 解析 Markdown 并生成路由
|
||||
- 打包为带 hash 路由的单个 HTML 入口
|
||||
- 复制引用的资源文件（图片、CSV 等）
|
||||
| 代码 | 含义 |
|
||||
|------|------|
|
||||
| `0` | 无错误（`--strict` 下存在警告也会失败） |
|
||||
| `1` | 存在错误（或 `--strict` 下存在警告） |
|
||||
| `2` | 用法 / IO 错误（例如目录不存在） |
|
||||
|
||||
**输出示例：**
|
||||
|
||||
```
|
||||
content/adventures/hollow-mill/adventure.md
|
||||
12:1 error TTTK-C001 :md-table reference "./npcs.csv" does not resolve
|
||||
hint: expected a file relative to this document, or an inline id defined in it
|
||||
40:8 warning TTTK-R002 spark-table first header "Name" is not a dice formula
|
||||
|
||||
2 errors, 1 warning
|
||||
12 files checked
|
||||
```
|
||||
|
||||
**诊断代码：**
|
||||
|
||||
| 代码 | 级别 | 说明 |
|
||||
|------|------|------|
|
||||
| `TTTK-S001` | error | Markdown 解析失败 |
|
||||
| `TTTK-S002` | error | 容器指令 `:::` 未闭合 |
|
||||
| `TTTK-D001` | error | 未知的 `:md-*` 元素名 |
|
||||
| `TTTK-R001` | error | 未知的代码块 `role=`（块内容会被静默丢弃） |
|
||||
| `TTTK-R002` | warning | `role=spark-table` 首列表头不是骰点公式 |
|
||||
| `TTTK-R003` | error | `role=declare` 解析失败（缺少 `key`/`expr` 等） |
|
||||
| `TTTK-R005` | error | `role=tag` 的 YAML 无法解析 |
|
||||
| `TTTK-R006` | error | `role=tag` 缺少 `tag:` 或元素未知 |
|
||||
| `TTTK-C001` | error | 内容引用无法解析（文件不存在，或内联 id 未定义） |
|
||||
| `TTTK-C002` | warning | 引用解析到的文件类型不符合预期 |
|
||||
| `TTTK-C003` | info | 同一文档中重复引用同一 CSV |
|
||||
| `TTTK-C004` | error | `:md-embed` 循环引用 |
|
||||
| `TTTK-L001` | error | 链接目标文件不存在 |
|
||||
| `TTTK-L002` | warning | `#锚点` 未匹配到任何标题 |
|
||||
| `TTTK-A001` | warning | 图标在 `assets/` 中不存在 |
|
||||
| `TTTK-A002` | warning | 图片不存在 |
|
||||
|
||||
**尚未实现的校验：** CSV 数据校验（解析错误、列数不一致、`label` 重复、`{{prop}}` 引用无效列）、畸形属性块、`role=declare` 被跳过的行。
|
||||
|
||||
**实现说明：**
|
||||
|
||||
- 校验复用与应用相同的 `scanDoc` 与内容注册表，因此通过校验意味着应用也能解析。
|
||||
- 定位基于**原始文件**（行号准确），围栏代码块与行内代码中的示例语句会被跳过。
|
||||
- 图标校验假设校验根目录之上不存在 `assets/` 目录。
|
||||
|
||||
**示例：**
|
||||
|
||||
```bash
|
||||
# 编译当前目录
|
||||
tttk compile
|
||||
# 校验当前目录
|
||||
tttk check
|
||||
|
||||
# 编译指定目录并输出到指定位置
|
||||
tttk compile ./content -o ./build
|
||||
# 校验指定目录并输出 JSON
|
||||
tttk check ./content --json
|
||||
|
||||
# 编译并部署
|
||||
tttk compile ./docs -o ./public && npm run preview
|
||||
# CI：只关注错误
|
||||
npx tttk check ./content --quiet
|
||||
```
|
||||
|
||||
### compile - 编译模式（未实现）
|
||||
|
||||
> **存根命令。** `compile` 目前不会产生任何输出，`--help` 中也已标明。
|
||||
> 请使用 `tttk serve` 预览内容、`tttk check` 校验内容。
|
||||
|
||||
原计划的用法如下（仅供参考，尚未实现）：
|
||||
|
||||
```bash
|
||||
tttk compile [dir] -o ./dist/output
|
||||
```
|
||||
|
||||
| 参数 | 说明 | 默认值 |
|
||||
|------|------|--------|
|
||||
| `[dir]` | 要编译的目录 | `.` (当前目录) |
|
||||
|
||||
| 选项 | 说明 | 默认值 |
|
||||
|------|------|--------|
|
||||
| `-o, --output <dir>` | 输出目录 | `./dist/output` |
|
||||
|
||||
## 输入文件
|
||||
|
||||
CLI 会搜索目录下的以下文件：
|
||||
@@ -106,6 +173,7 @@ CLI 会搜索目录下的以下文件：
|
||||
- `.md` - Markdown 文档
|
||||
- `.csv` - 表格数据
|
||||
- `.yarn` - Yarn Spinner 叙事文件
|
||||
- `.svg` - 矢量图标
|
||||
|
||||
### 文件组织建议
|
||||
|
||||
@@ -126,19 +194,21 @@ my-ttrpg-content/
|
||||
|
||||
### 相对路径引用
|
||||
|
||||
若 Markdown 文件通过相对路径引用了其他文件（如图片、CSV），CLI 会在打包时自动处理这些引用：
|
||||
若 Markdown 文件通过相对路径引用了其他文件（如图片、CSV），引用会相对于当前文档所在目录解析：
|
||||
|
||||
```markdown
|
||||
<!-- 引用同目录下的 CSV -->
|
||||
:table[./sparks.csv]
|
||||
:md-table[./sparks.csv]
|
||||
|
||||
<!-- 引用子目录的图片 -->
|
||||
|
||||
|
||||
<!-- 引用上级目录的文件 -->
|
||||
:deck[../data/cards.csv]
|
||||
:md-deck[../data/cards.csv]
|
||||
```
|
||||
|
||||
使用 `tttk check` 可以校验这些引用是否都能解析。
|
||||
|
||||
## 开发服务器特性
|
||||
|
||||
### 实时索引
|
||||
@@ -165,14 +235,17 @@ my-ttrpg-content/
|
||||
tttk serve -p 8080
|
||||
```
|
||||
|
||||
### 编译输出为空
|
||||
### check 报告了很多警告
|
||||
|
||||
检查输入目录是否包含 `.md` 文件：
|
||||
先用 `--quiet` 只看错误，或在 CI 中配合 `--strict`：
|
||||
|
||||
```bash
|
||||
# 查看目录内容
|
||||
ls -R ./content
|
||||
|
||||
# 重新编译
|
||||
tttk compile ./content -o ./dist/output
|
||||
tttk check ./content --quiet
|
||||
tttk check ./content --json
|
||||
```
|
||||
|
||||
警告通常确有其事（例如锚点或图标不存在），建议逐条确认。
|
||||
|
||||
### compile 没有输出
|
||||
|
||||
`compile` 目前是未实现的存根命令，不会产生任何输出。请使用 `tttk serve` 预览，使用 `tttk check` 校验。
|
||||
|
||||
Reference in New Issue
Block a user