ttrpg-tools/docs/markdown.md

Markdown 编写说明

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

基础语法

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

• GFM - GitHub Flavored Markdown
• marked-alert - 警告/提示块
• marked-gfm-heading-id - 标题 ID
• marked-directive - 指令语法

指令语法

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

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

语法说明

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

支持多个嵌套指令：

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

分栏布局

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

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

语法说明：

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

多栏示例：

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

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

图标语法

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

:[attack]  :[defense]  :[potion]  :[sword]

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

配置图标前缀

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

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

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

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

组件库

🎲 骰子组件 (md-dice)

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

功能：

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

属性：

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

示例：

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

🔗 链接组件 (md-link)

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

功能：

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

属性：

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

示例：

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

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

🖼️ 背景组件 (md-bg)

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

功能：

• 将图片设置为当前文章卡片的背景
• 自动覆盖整个卡片区域

属性：

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

示例：

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

# 地牢探险

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

📍 标记组件 (md-pins)

: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

示例：

<!-- 固定标记模式 - 字母标签（默认从 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)

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

CSV 格式要求：

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

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

特殊列：

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

属性：

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

变量引用语法：

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

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

Front Matter 支持：

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

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

示例：

<!-- 基础表格 -->
: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 列时：

| 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)

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

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 格式文件。

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

🪙 代币组件 (md-token)

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

:md-token[./token.png]

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

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

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

功能：

• 使用 Three.js 渲染 3D 模型
• 支持鼠标拖拽旋转
• 自动旋转展示

📋 命令追踪器 (md-commander)

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

: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 代码块创建自定义标签：

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

渲染为：

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

Mermaid 图表

支持 mermaid 流程图：

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

支持的图表类型：

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

警告/提示块

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

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

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

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

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

文件引用

相对路径

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

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

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

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

路径解析规则

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

样式定制

使用 Tailwind 类

组件支持 Tailwind CSS 类：

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

自定义 CSS

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

最佳实践

内容组织

# 章节标题

这里是章节内容。

## 子章节

### 规则说明

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

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

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

性能优化

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

可访问性

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