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

图标语法

使用简单的 :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)

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

功能：

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

属性：

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

示例：

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

🔗 链接组件 (md-link)

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

功能：

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

属性：

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

示例：

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

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

🖼️ 背景组件 (md-bg)

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

功能：

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

属性：

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

示例：

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

# 地牢探险

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

🪙 代币组件 (md-token)

: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 文件

示例：

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

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

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

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

功能：

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

属性：

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

Yarn 文件格式：

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

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

示例：

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

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

📋 命令追踪器 (md-commander)

: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	清空追踪

示例：

<!-- 基础追踪器 -->
: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 代码块创建自定义标签：

```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]
> 这是危险警告

文件引用

相对路径

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

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

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

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

路径解析规则

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

样式定制

使用 Tailwind 类

组件支持 Tailwind CSS 类：

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

自定义 CSS

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

最佳实践

内容组织

# 章节标题

这里是章节内容。

## 子章节

### 规则说明

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

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

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

性能优化

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

可访问性

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