462 lines
8.4 KiB
Markdown
462 lines
8.4 KiB
Markdown
# 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]
|
||
|
||
<!-- 引用图片 -->
|
||
|
||
```
|
||
|
||
### 路径解析规则
|
||
|
||
- 所有路径相对于当前 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` 文本
|
||
- 使用语义化标题层级
|
||
- 确保颜色对比度
|