# TTTK — Tabletop Toolkit

A TTRPG content preview and validation tool based on `solid.js` and `rsbuild`. Write markdown, preview in browser, validate before you ship.

## 快速开始

```bash
# 无需安装，直接使用
npx tttk serve ./content

# 校验内容（存在错误时退出码为 1）
npx tttk check ./content
```

## 文档导航

| 文档 | 说明 |
|------|------|
| [📖 CLI 使用说明](./docs/cli.md) | CLI 安装、命令和用法 |
| [🔤 语法参考](./docs/reference.md) | 自定义元素、代码块角色与属性目录（由 `known.ts` 生成） |
| [📦 npm](https://www.npmjs.com/package/tttk) | `npx tttk serve ./content` |
| [🛠️ 开发指南](./docs/development.md) | 项目结构、开发规范和构建 |
| [📝 Markdown 编写说明](./docs/markdown.md) | Markdown 语法和组件用法 |
| [📊 CSV 编写说明](./docs/csv.md) | CSV 文件格式、字段定义、变量语法 |
| [🤖 MCP 服务器说明](./docs/mcp.md) | AI 助手集成、卡牌生成工具 |

## 功能概览

- **CLI 工具**: `tttk serve` 预览模式、`tttk check` 校验模式（`tttk compile` 尚未实现）
- **Markdown 解析**: 支持指令语法、YAML 标签、mermaid 图表
- **TTRPG 组件**: 骰子、表格、卡牌、标记、命令追踪器等

## 核心组件

| 组件 | 语法 | 说明 |
|------|------|------|
| 🎲 骰子 | `:md-dice[2d6+d8]` | 掷骰并记录结果 |
| 📊 表格 | `:md-table[./data.csv]` | 标签页式表格 |
| 🃏 卡牌 | `:md-deck[./cards.csv]` | 卡牌布局（推荐 `yaml role=tag` 写法） |
| 📍 标记 | `:md-pins[./map.png]{pins="A:25,50"}` | 图片标记 |
| 📋 追踪器 | `:md-commander[./commands.csv]` | 命令历史和状态追踪 |

## 技术栈

- **前端**: Solid.js 1.9+
- **构建**: Rsbuild
- **样式**: Tailwind CSS 4
- **Markdown**: marked + marked-directive
- **测试**: Jest

## 许可证

MIT