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]
:::
```

## 分栏布局

使用简单的分隔符语法创建多栏布局：

```markdown
|---
左侧栏内容
-|-
右侧栏内容
---
```

**语法说明：**

| 分隔符 | 说明 |
|--------|------|
| `\|---` | 开始分栏容器 |
| `-|-` | 分隔各栏 |
| `---` | 结束分栏容器 |

**多栏示例：**

```markdown
|---
第一栏
-|-
第二栏
-|--
第三栏（更宽）
---
```

`-|--` 中的额外 `-` 会添加 `-N` 后缀到 CSS 类名（如 `col-2`），可用于自定义宽度。

## 图标语法

使用简单的 `:[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
:md-dice[2d6+d8]
:md-dice[1d20+5]{key="attack"}
```

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

**属性：**

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

**示例：**

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

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

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

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

**属性：**

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

**示例：**

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

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

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

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

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

**属性：**

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

**示例：**

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

# 地牢探险

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

### 📍 标记组件 (md-pins)

```markdown
:md-pins[./images/map.png]{pins="A:30,40 B:10,30" fixed}
:md-pins[./images/city-map.png]
:md-pins[./images/dungeon.png]{labelStart="1"}
:md-pins[./images/quest.png]{labelStart="C"}
```

**功能：**
- 在图片上显示标记点（A-Z, AA-ZZ, AAA-ZZZ... 或数字）
- `fixed` 模式：仅显示标记，不可编辑
- 非 fixed 模式：点击图片添加标记，点击标记删除
- 提供复制按钮生成标记代码
- 支持自定义标签起始值（字母或数字）

**属性：**

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `pins` | string | `""` | 标记列表，格式 `"A:30,40 B:10,30"` (标签：x,y) |
| `fixed` | boolean | `false` | 是否为固定模式（只读） |
| `labelStart` | string | `"A"` | 标签起始值，支持字母（如 `"A"`, `"C"`）或数字（如 `"1"`, `"7"`） |

**标签生成规则：**

| 起始值类型 | 说明 | 示例 |
|------|------|------|
| 字母（默认） | 从起始字母开始，按 A-Z, AA-ZZ, AAA-ZZZ 顺序 | `A` → A, B, C...; `C` → C, D, E... |
| 数字 | 从起始数字开始递增 | `1` → 1, 2, 3...; `7` → 7, 8, 9... |

**字母标签序列（从 A 开始）：**
- 0-25: A-Z
- 26-51: AA-ZZ
- 52-77: AAA-ZZZ

**示例：**

```markdown
<!-- 固定标记模式 - 字母标签（默认从 A 开始） -->
:md-pins[./images/battle-map.png]{pins="A:25,50 B:75,30 C:50,80" fixed}

<!-- 可编辑模式 - 点击添加标记 - 从 A 开始 -->
:md-pins[./images/blank-map.png]

<!-- 数字标签 - 从 1 开始 -->
:md-pins[./images/dungeon.png]{labelStart="1"}

<!-- 数字标签 - 从 7 开始 -->
:md-pins[./images/cave.png]{labelStart="7"}

<!-- 字母标签 - 从 C 开始 -->
:md-pins[./images/quest-map.png]{labelStart="C"}

<!-- 自定义标签 + 预设标记 -->
:md-pins[./images/map.png]{pins="5:30,40 6:75,30" labelStart="5" fixed}

<!-- 复制生成的格式 -->
:md-pins[./images/map.png]{pins="A:30,40 B:10,30" fixed}
```

### 📊 表格组件 (md-table)

```markdown
:md-table[./data.csv]
:md-table[./data.csv]{roll=true}
:md-table[./data.csv]{roll=true remix=true}
```

**CSV 格式要求：**

```csv
label,body,group
第一页，这是**第一页**的内容，group1
第二页，这是*第二页*的内容，group1
第三页，这是第三页的内容，group2
```

- 使用英文逗号分隔
- 支持 `#` 开头的注释行
- 包含逗号或 `#` 的字段用双引号包裹

**特殊列：**

| 列名 | 说明 |
|------|------|
| `label` | 标签页名称 |
| `body` | 标签页内容（支持 Markdown） |
| `group` | 分组标识（可选） |

**属性：**

| 属性 | 类型 | 说明 |
|------|------|------|
| `roll` | boolean | 添加随机切换按钮 |
| `remix` | boolean | `{{prop}}` 引用随机行内容 |

**变量引用语法：**

在 `body` 列中可使用 `{{prop}}` 引用同行其他列：

```csv
label,name,description,body
战士，约翰，勇敢的战士，{{name}}是一位{{description}}。
```

**Front Matter 支持：**

CSV 可包含 YAML front matter，所有行会继承这些属性：

```csv
---
source: 玩家手册
version: 1.0
---
label,name,description
1，战士，近战专家
2，法师，奥术施法者
```

**示例：**

```markdown
<!-- 基础表格 -->
:md-table[./npcs.csv]

<!-- 带随机切换 -->
:md-table[./encounters.csv]{roll=true}

<!-- 随机引用变量 -->
:md-table[./quests.csv]{roll=true remix=true}
```

**自动表格转换：**

标准 Markdown 表格会自动转换为 `md-table` 组件，当表头包含 `label` 或 `md-table-label` 列时：

```markdown
| label | name | description |
|-------|------|-------------|
| 1 | 战士 | 近战专家 |
| 2 | 法师 | 奥术施法者 |
```

自动转换为 `:md-table` 组件。

**特殊表头标识：**

| 表头 | 效果 |
|------|------|
| `label` 或 `md-table-label` | 转换为 md-table |
| `md-roll-label` 或骰子格式（如 `1d6`） | 添加 `roll=true` |
| `md-remix-label` | 添加 `roll=true remix=true` |

### 🃏 卡牌组件 (md-deck)

```markdown
:md-deck[./cards.csv]{grid="5x8" layers="title:1,1-5,1f8 body:1,5-5,8f3"}
```

**CSV 格式：**

```csv
label,title,body
1,卡牌名称，这张卡牌的**效果**描述
2,另一张牌，更多效果
```

**属性：**

| 属性 | 类型 | 说明 |
|------|------|------|
| `grid` | string | 卡牌布局（行 x 列） |
| `layers` | string | 图层定义 |

**图层语法：**

```
layers="字段：起始行，起始列 - 结束列，字体大小"
```

示例：`title:1,1-5,1f8` 表示 title 字段从第 1 行开始，占据 1-5 列，8mm字体。

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

用于展示分支叙事结构，支持 Yarn Spinner 格式文件。

```markdown
:md-yarn-spinner[./story.yarn]
```

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

用于展示游戏代币/棋子。

```markdown
:md-token[./token.png]
```

### 🎨 代币预览组件 (md-token-viewer)

用于 3D 预览 3MF 格式的代币模型。

```markdown
:md-token-viewer[./token.3mf]
```

**功能：**
- 使用 Three.js 渲染 3D 模型
- 支持鼠标拖拽旋转
- 自动旋转展示

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

支持命令历史和状态追踪。

```markdown
:md-commander
```

**追踪器命令：**

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

**Emmet 简写语法：**

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

**属性类型：**

| 类型 | 格式 | 显示 |
|------|------|------|
| progress | `x/y` | 进度条 |
| count | 整数 | 数字计数器 |
| string | 文本 | 文本字段 |

## 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
<!-- 引用同目录文件 -->
:md-table[./data.csv]

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

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

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

### 路径解析规则

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

## 样式定制

### 使用 Tailwind 类

组件支持 Tailwind CSS 类：

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

### 自定义 CSS

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

## 最佳实践

### 内容组织

```markdown
# 章节标题

这里是章节内容。

## 子章节

### 规则说明

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

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

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

### 性能优化

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

### 可访问性

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