ttrpg-tools/docs/markdown.md

# Markdown 编写说明

本文档介绍 TTRPG Tools 支持的 Markdown 扩展语法和组件用法。

## 基础语法

使用标准 Markdown 语法，支持以下扩展：

- [GFM](https://github.github.com/gfm/) - GitHub Flavored Markdown
- [marked-alert](https://github.com/Insidify/marked-alert) - 警告/提示块
- [marked-gfm-heading-id](https://github.com/markedjs/marked-gfm-heading-id) - 标题 ID
- [marked-directive](https://github.com/fengzilong/marked-directive) - 指令语法

## 指令语法

通过 `marked-directive` 支持自定义组件插入：

```markdown
:component-name[content]{key="value" another="test"}
```

### 语法说明

| 部分 | 说明 | 示例 |
|------|------|------|
| `:name` | 组件名称 | `:dice` |
| `[content]` | 内容参数 | `[2d6+d8]` |
| `{attrs}` | 属性对象 | `{key="attack"}` |

### 嵌套指令

```markdown
::: container
这里是容器内容
:dice[1d20]
:::
```

## 图标语法

使用简单的 `:icon-name` 语法插入图标：

```markdown
:attack  :defense  :potion  :sword
```

图标会渲染为 `<icon class="icon-attack"></icon>` 形式。

### 配置图标前缀

可通过 `iconPath` 属性指定图标目录：

```markdown
<Article src="/content/page.md" iconPath="./assets/icons" />
```

或使用空字符串禁用图标前缀：

```markdown
<Article src="/content/page.md" iconPath="" />
```

## 组件库

### 🎲 骰子组件 (md-dice)

```markdown
:dice[2d6+d8]
:dice[1d20+5]{key="attack"}
```

**功能：**
- 点击骰子图标执行掷骰
- 点击文本重置为公式
- `key` 属性将结果记录到 URL 参数中 (`?dice-attack=15`)

**属性：**

| 属性 | 类型 | 说明 |
|------|------|------|
| `key` | string | 用于 URL 参数记录的标识 |

**示例：**

```markdown
攻击检定 :dice[1d20+5]{key="attack"}
伤害掷骰 :dice[2d6+3]{key="damage"}
```

### 🔗 链接组件 (md-link)

```markdown
:link[./other-page.md]
:link[./rules.md#combat-section]
```

**功能：**
- 点击链接在当前页面内展开显示目标文章内容
- 支持 `#section` 语法显示特定章节
- 支持相对路径引用

**属性：**

| 属性 | 类型 | 说明 |
|------|------|------|
| （无） | - | 内容即为链接目标路径 |

**示例：**

```markdown
查看完整规则 :link[./rules.md]

查看战斗章节 :link[./rules.md#combat]
```

### 🖼️ 背景组件 (md-bg)

```markdown
:bg[./images/background.jpg]
:bg[./images/pattern.png]{fit="contain"}
```

**功能：**
- 将图片设置为当前文章卡片的背景
- 自动覆盖整个卡片区域

**属性：**

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `fit` | `cover` \| `contain` \| `fill` \| `none` \| `scale-down` | `cover` | 背景适配方式 |

**示例：**

```markdown
:bg[./images/dungeon-bg.jpg]{fit="cover"}

# 地牢探险

这里是地牢的描述内容...
```

### 🪙 代币组件 (md-token)

```markdown
:md-token[./token-image.png]
:md-token[./hero.png]{size=60 defaultThickness=2.5}
```

**功能：**
- 将 2D 图片转换为 3D 打印模型
- 自动进行图像矢量追踪分层
- 支持预览和导出 STL 文件

**属性：**

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `size` | number | `50` | 模型整体尺寸 (mm) |
| `defaultThickness` | number | `2` | 默认图层厚度 (mm) |

**使用流程：**

1. 引用图片（PNG/JPG 等）
2. 等待矢量追踪完成
3. 在设置面板调整图层厚度
4. 点击「生成 3D 模型」
5. 预览并下载 STL 文件

**示例：**

```markdown
<!-- 基础代币 -->
:md-token[./images/warrior-token.png]

<!-- 指定尺寸 -->
:md-token[./images/dragon.png]{size=75 defaultThickness=3}
```

### 🧶 叙事线组件 (md-yarn-spinner)

```markdown
:md-yarn-spinner[./story.yarn]{start="start"}
```

**功能：**
- 运行 Yarn Spinner 叙事脚本
- 显示对话历史和选项
- 支持命令和变量替换

**属性：**

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `start` | string | `start` | 起始节点名称 |

**Yarn 文件格式：**

```yarn
title: start
tags: 
colorID: 0
position: 0,0
---
NPC: 欢迎来到村庄！
玩家：谢谢！[[继续]]
===

title: 继续
tags:
colorID: 0
position: 200,0
---
NPC: 有什么我可以帮你的吗？
-> 询问任务
    最近有什么危险的任务吗？
-> 离开
    再见！
    [[结束]]
===
```

**示例：**

```markdown
:md-yarn-spinner[./dialogues/village-elder.yarn]

:md-yarn-spinner[./quest-branch.yarn]{start="intro"}
```

### 📋 命令追踪器 (md-commander)

```markdown
:md-commander
:md-commander[./commands.csv]{placeholder="输入命令..."}
```

**功能：**
- 命令历史视图
- 追踪器视图（角色状态、进度等）
- 支持 Emmet 简写语法
- 命令自动补全

**属性：**

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `placeholder` | string | - | 输入框占位符 |
| `class` | string | - | 额外 CSS 类 |
| `height` | string | `400px` | 组件高度 |
| `commandTemplates` | string | - | CSV 模板文件路径 |

**追踪器命令语法：**

```
track npc#john.dwarf.warrior[hp=4/4 ac=15 name="John"]
```

**Emmet 简写语法：**

- `#id` - 设置 ID
- `.class` - 添加类别
- `[attr=value]` - 设置属性

**属性类型：**

| 类型 | 格式 | 显示 |
|------|------|------|
| `progress` | `x/y` | 进度条 (如 `hp=4/4`) |
| `count` | 整数 | 数字计数器 (如 `ac=15`) |
| `string` | 文本 | 文本字段 (如 `name="John"`) |

**内置命令：**

| 命令 | 说明 |
|------|------|
| `track` | 添加追踪项 |
| `remove` | 移除追踪项 |
| `update` | 更新属性 |
| `clear` | 清空追踪 |

**示例：**

```markdown
<!-- 基础追踪器 -->
:md-commander

<!-- 带占位符 -->
:md-commander{placeholder="输入 /help 查看命令"}

<!-- 从 CSV 加载命令模板 -->
:md-commander[./my-commands.csv]

<!-- 示例追踪命令 -->
track enemy#goblin.soldier[hp=7/7 ac=12]
track ally#cleric[hp=24/24 spells=4/4]
```

### 📁 文件树 (FileTree)

文件树组件自动在侧边栏显示，无需手动插入。

**功能：**
- 自动扫描内容目录
- 显示文件层级结构
- 支持文件夹展开/收起
- 显示当前文件的标题导航

**目录结构示例：**

```
content/
├── index.md           # 首页
├── rules/
│   ├── index.md       # 规则首页
│   ├── combat.md      # 战斗规则
│   └── magic.md       # 魔法系统
└── characters/
    └── npc-list.md    # NPC 列表
```

侧边栏会自动显示：
- 📁 rules/
  - 📄 combat.md
  - 📄 magic.md

## YAML 标签

使用 ```yaml/tag 代码块创建自定义标签：

````markdown
```yaml/tag
tag: tag-name
class: custom-class
id: my-id
body: 标签内容
```
````

渲染为：

```html
<tag-name id="my-id" class="custom-class">标签内容</tag-name>
```

## Mermaid 图表

支持 mermaid 流程图：

````markdown
```mermaid
graph TD
    A[开始] --> B{选择}
    B -->|选项 1| C[结果 1]
    B -->|选项 2| D[结果 2]
```
````

支持的图表类型：

- flowchart - 流程图
- sequenceDiagram - 时序图
- classDiagram - 类图
- stateDiagram - 状态图
- erDiagram - ER 图
- pie - 饼图

## 警告/提示块

```markdown
> [!NOTE]
> 这是一条备注

> [!TIP]
> 这是一条提示

> [!IMPORTANT]
> 这是重要信息

> [!WARNING]
> 这是警告信息

> [!CAUTION]
> 这是危险警告
```

## 文件引用

### 相对路径

```markdown
<!-- 引用同目录文件 -->
:table[./data.csv]

<!-- 引用子目录文件 -->
:deck[./cards/deck.csv]

<!-- 引用上级目录文件 -->
:table[../shared/npcs.csv]

<!-- 引用图片 -->
![地图](./images/map.png)
```

### 路径解析规则

- 所有路径相对于当前 Markdown 文件
- 支持 `.` 和 `..` 导航
- 自动处理 URL 编码

## 样式定制

### 使用 Tailwind 类

组件支持 Tailwind CSS 类：

```markdown
:dice[1d20]{class="text-red-500"}
```

### 自定义 CSS

```css
/* 在 styles.css 中添加 */
.md-dice {
  @apply text-blue-600 hover:text-blue-800;
}
```

## 最佳实践

### 内容组织

```markdown
# 章节标题

这里是章节内容。

## 子章节

### 规则说明

:dice[2d6] 掷骰决定结果。

:table[./options.csv]{roll=true}

> [!TIP]
> 这是一个有用的提示。
```

### 性能优化

- 大型 CSV 文件使用 `group` 列分组
- 图片使用适当分辨率
- 避免过多嵌套组件

### 可访问性

- 为图片添加 `alt` 文本
- 使用语义化标题层级
- 确保颜色对比度