feat(docs): add component documentation entries and refactor dialog

rendering

src/components/DocDialog.tsx

@@ -150,19 +150,12 @@ const DocContent: Component<{ entry: DocEntry }> = (props) => {
         </div>
       </Show>
 
-      <div class="mb-6">
+      <div class="prose-sm max-w-none">
         <h3 class="text-sm font-semibold text-gray-500 uppercase mb-2">示例</h3>
         <div class="bg-gray-50 border border-gray-200 rounded-lg p-4 text-sm leading-relaxed whitespace-pre-wrap font-mono text-gray-800">
-          {e.examples}
+          {e.body}
         </div>
       </div>
-
-      <div>
-        <h3 class="text-sm font-semibold text-gray-500 uppercase mb-2">
-          使用场景
-        </h3>
-        <p class="text-sm text-gray-600">{e.usage}</p>
-      </div>
     </div>
   );
 };

src/components/doc-data.ts

@@ -1,3 +1,5 @@
+import yaml from "js-yaml";
+
 export interface DocEntry {
   tag: string;
   icon: string;
@@ -5,350 +7,72 @@ export interface DocEntry {
   description: string;
   syntax: string;
   props: { name: string; type: string; default?: string; desc: string }[];
-  examples: string;
+  /** Markdown body (everything after frontmatter ---) */
-  usage: string;
+  body: string;
 }
 
-export const docEntries: DocEntry[] = [
+/** Splits frontmatter and markdown body from a raw .md string. */
-  {
+function parseFrontmatter(raw: string): Record<string, unknown> | null {
-    tag: "md-dice",
+  const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
-    icon: "🎲",
+  if (!match) return null;
-    title: "骰子组件",
+  try {
-    description: "点击文字执行掷骰，可用于属性检定、伤害投掷等场景。",
+    return yaml.load(match[1]) as Record<string, unknown>;
-    syntax: ':md-dice[2d6+d8]{key="attack"}',
+  } catch {
-    props: [
+    return null;
-      {
+  }
-        name: "key",
+}
-        type: "string",
-        desc: "URL 参数标识，结果记录到 ?dice-key=15",
-      },
-    ],
-    examples: `**攻击检定：** :md-dice[1d20+5]{key="attack"}
 
-**伤害掷骰：** :md-dice[2d6+3]{key="damage"}
+function getBody(raw: string): string {
+  const match = raw.match(/^---\n[\s\S]*?\n---\n?([\s\S]*)$/);
+  return match ? match[1] : raw;
+}
 
-**优势检定：** :md-dice[2d20k1+5]{key="advantage"}
+/** Glob import all .md files in src/doc-entries/ */
+const modules = import.meta.webpackContext("./", {
+  recursive: false,
+  regExp: /\.md$/,
+});
 
-点击掷骰文字执行投掷，再次点击重置为公式。`,
+/** Lazy-loaded doc entries, parsed on first access. */
-    usage: "用于技能检定、攻击命中、伤害计算等需要随机数的场景。",
+let _entries: DocEntry[] | null = null;
-  },
-  {
-    tag: "md-table",
-    icon: "📊",
-    title: "表格组件",
-    description:
-      "将 CSV 数据转换为可切换标签页的表格，支持随机抽取和变量引用。",
-    syntax: ":md-table[./data.csv]{roll=true remix=true}",
-    props: [
-      { name: "roll", type: "boolean", desc: "显示随机切换按钮" },
-      { name: "remix", type: "boolean", desc: "支持 {{prop}} 引用同行其他列" },
-    ],
-    examples: `**基础表格：**
-\`\`\`markdown
-:md-table[./npcs.csv]
-\`\`\`
 
-**带随机抽取：**
+export function loadDocEntries(): DocEntry[] {
-\`\`\`markdown
+  if (_entries) return _entries;
-:md-table[./encounters.csv]{roll=true}
-\`\`\`
 
-**随机 + 变量引用：**
+  const entries: DocEntry[] = [];
-\`\`\`markdown
-:md-table[./quests.csv]{roll=true remix=true}
-\`\`\`
 
-CSV 要求包含 label, body 列，可选 group 列分组。支持 YAML front matter 继承行属性。`,
+  for (const key of modules.keys()) {
-    usage: "用于 NPC 列表、遭遇表、宝物生成、随机事件等结构化数据。",
+    const mod = modules(key);
-  },
+    const raw =
-  {
+      typeof mod === "string"
-    tag: "md-link",
+        ? mod
-    icon: "🔗",
+        : ((mod as { default?: string }).default ?? "");
-    title: "链接组件",
+    if (!raw) continue;
-    description: "点击链接在当前页面内展开显示目标文章内容，支持章节定位。",
-    syntax: ":md-link[./rules.md#combat]",
-    props: [],
-    examples: `**展开完整文档：**
-:md-link[./rules.md]
 
-**展开特定章节：**
+    const fm = parseFrontmatter(raw);
-:md-link[./rules.md#combat]
+    if (!fm) continue;
 
-点击链接即可内联展开目标内容，再次点击折叠。`,
+    const body = getBody(raw);
-    usage: "用于引用规则书章节、怪物数据、快速预览等场景。",
-  },
-  {
-    tag: "md-pins",
-    icon: "📍",
-    title: "标记组件",
-    description:
-      "在地图或图片上添加可编辑或固定的位置标记，支持字母或数字标签。",
-    syntax: ':md-pins[./images/map.png]{pins="A:30,40 B:10,30" fixed}',
-    props: [
-      {
-        name: "pins",
-        type: "string",
-        default: '""',
-        desc: '标记列表，格式 "A:x,y B:x,y"',
-      },
-      {
-        name: "fixed",
-        type: "boolean",
-        default: "false",
-        desc: "固定模式（只读不可编辑）",
-      },
-      {
-        name: "labelStart",
-        type: "string",
-        default: '"A"',
-        desc: "标签起始值，支持字母或数字",
-      },
-    ],
-    examples: `**固定标记（只读）：**
-:md-pins[./images/battle-map.png]{pins="A:25,50 B:75,30" fixed}
 
-**可编辑标记：**
+    entries.push({
-:md-pins[./images/blank-map.png]
+      tag: fm.tag as string,
+      icon: fm.icon as string,
+      title: fm.title as string,
+      description: fm.description as string,
+      syntax: fm.syntax as string,
+      props: (fm.props as DocEntry["props"]) ?? [],
+      body,
+    });
+  }
 
-**数字标签：**
+  // Sort alphabetically by tag
-:md-pins[./images/dungeon.png]{labelStart="1"}
+  entries.sort((a, b) => a.tag.localeCompare(b.tag));
+  _entries = entries;
+  return entries;
+}
 
-非 fixed 模式下点击图片添加标记，点击标记删除。`,
+/**
-    usage: "用于战斗地图标注、地牢房间标记、任务地点指示等。",
+ * Direct static array for the DocDialog sidebar — uses webpackContext
-  },
+ * so all .md files in doc-entries/ are bundled automatically.
-  {
+ */
-    tag: "md-font",
+export const docEntries = loadDocEntries();
-    icon: "🔤",
-    title: "字体组件",
-    description:
-      "设置整个文档的字体和文字颜色，支持 Google Fonts、emfont 和系统本地字体三种来源。",
-    syntax:
-      ':md-font[Noto Sans SC]{source="google" weight="400" color="#ff00dd"}',
-    props: [
-      {
-        name: "source",
-        type: "google | emfont | local",
-        default: "local",
-        desc: "字体来源",
-      },
-      { name: "weight", type: "string", default: '"400"', desc: "字体粗细" },
-      {
-        name: "color",
-        type: "string",
-        desc: "文字颜色（CSS 颜色值，如 #ff00dd、rgb(255,0,0)）",
-      },
-    ],
-    examples: `**Google 字体：**
-:md-font[Noto Sans SC]{source="google"}
-
-**Emfont 字体：**
-:md-font[Source Han Serif]{source="emfont" weight="700"}
-
-**本地字体（默认）：**
-:md-font[STSong]
-
-**设置文字颜色：**
-:md-font[Noto Sans SC]{source="google" color="#1a1a2e"}
-
-:md-font[Noto Sans SC]{source="google" weight="700" color="crimson"}
-
-字体和颜色将应用到整个文档卡片。`,
-    usage: "用于切换文档的显示字体和文字颜色，适配不同风格需求。",
-  },
-  {
-    tag: "md-bg",
-    icon: "🖼️",
-    title: "背景组件",
-    description: "设置背景图片或纯色作为文章卡片背景，支持多种适配方式。",
-    syntax: ":md-bg[#ff00dd]",
-    props: [
-      {
-        name: "fit",
-        type: "cover | contain | fill | none | scale-down",
-        default: "cover",
-        desc: "背景适配方式（仅图片时生效）",
-      },
-    ],
-    examples: `**设置背景图：**
-:md-bg[./images/dungeon-bg.jpg]{fit="cover"}
-
-**设置纯色背景：**
-:md-bg[#2a1a3a]
-
-:md-bg[rgb(200,50,50)]
-
-:md-bg[#ff00dd]
-
-支持图片路径或任意 CSS 颜色值（hex、rgb、颜色名等）。`,
-    usage:
-      "用于营造场景氛围，如地牢、森林、城镇等不同环境的背景，或纯色区分不同主题。",
-  },
-  {
-    tag: "md-font",
-    icon: "🔤",
-    title: "字体组件",
-    description:
-      "设置整个文档的字体，支持 Google Fonts、emfont 和系统本地字体三种来源。",
-    syntax: ':md-font[Noto Sans SC]{source="google" weight="400"}',
-    props: [
-      {
-        name: "source",
-        type: "google | emfont | local",
-        default: "local",
-        desc: "字体来源",
-      },
-      { name: "weight", type: "string", default: '"400"', desc: "字体粗细" },
-    ],
-    examples: `**Google 字体：**
-:md-font[Noto Sans SC]{source="google"}
-
-**Emfont 字体：**
-:md-font[Source Han Serif]{source="emfont" weight="700"}
-
-**本地字体（默认）：**
-:md-font[STSong]
-
-字体将应用到整个文档卡片。`,
-    usage: "用于切换文档的显示字体，适配不同风格需求。",
-  },
-  {
-    tag: "md-border",
-    icon: "🖼️",
-    title: "边框组件",
-    description: "为文档卡片添加纯色或图片边框，支持指定边、样式和重复模式。",
-    syntax: ":md-border[#3b82f6]{.l .dashed}",
-    props: [
-      {
-        name: "width",
-        type: "string",
-        default: "纯色 .1mm，图片 2mm",
-        desc: "边框宽度",
-      },
-      {
-        name: "slice",
-        type: "string",
-        default: '"10"',
-        desc: "border-image-slice（仅图片模式）",
-      },
-    ],
-    examples: `**纯色左边框：**
-:md-border[#3b82f6]{.l}
-
-**虚线上下边框：**
-:md-border[red]{.t .b .dashed width=".2mm"}
-
-**图片边框：**
-:md-border[./images/frame.png]{.all .round}
-
-**左右图片竖条：**
-:md-border[./images/ornament.png]{.l .r .repeat}
-
-边 class：\`t\` \`b\` \`l\` \`r\` \`all\`（默认）\n样式 class：\`solid\` \`dashed\` \`dotted\` \`double\`\n图片 class：\`stretch\` \`repeat\` \`round\` \`space\``,
-    usage: "用于装饰文档卡片，配合背景和字体营造特定风格。",
-  },
-  {
-    tag: "md-embed",
-    icon: "📄",
-    title: "嵌入组件",
-    description: "将另一个 Markdown 文件的内容内联嵌入到当前文档中。",
-    syntax: ":md-embed[./rules.md#combat]",
-    props: [],
-    examples: `**嵌入完整文档：**
-:md-embed[./rules.md]
-
-**嵌入指定章节：**
-:md-embed[./rules.md#combat]
-
-嵌入后内容直接在当前位置显示，包括其中的表格、骰子等组件也会正常渲染。`,
-    usage: "用于在文档中引用通用规则、重复使用的数据表格等。",
-  },
-  {
-    tag: "md-deck",
-    icon: "🃏",
-    title: "卡牌组件",
-    description: "将 CSV 数据渲染为卡牌布局，支持自定义网格和图层的排版。",
-    syntax:
-      ':md-deck[./cards.csv]{grid="5x8" layers="title:1,1-5,1f8 body:1,5-8,8f3"}',
-    props: [
-      { name: "grid", type: "string", desc: "卡牌布局，格式 行x列" },
-      {
-        name: "layers",
-        type: "string",
-        desc: "图层定义，格式 字段:行,列-列,字号",
-      },
-    ],
-    examples: `**基础卡牌：**
-:md-deck[./spells.csv]{grid="3x3"}
-
-**多层卡牌：**
-:md-deck[./cards.csv]{grid="5x8" layers="title:1,1-5,1f8 body:1,5-8,8f3"}
-
-CSV 包含 label 和显示字段列，通过图层定义控制各字段的位置和大小。`,
-    usage: "用于法术卡、物品卡、NPC 卡等可打印的卡牌排版。",
-  },
-  {
-    tag: "md-yarn-spinner",
-    icon: "🧶",
-    title: "叙事线组件",
-    description: "展示 Yarn Spinner 格式的分支叙事结构，支持对话选择和分支。",
-    syntax: ":md-yarn-spinner[./story.yarn]",
-    props: [],
-    examples: `**加载叙事文件：**
-:md-yarn-spinner[./story.yarn]
-
-Yarn Spinner 是用于游戏对话系统的格式，支持选项、条件分支和变量。`,
-    usage: "用于互动故事、分支对话、冒险剧本等。",
-  },
-  {
-    tag: "md-token",
-    icon: "🪙",
-    title: "代币组件",
-    description: "展示游戏代币或棋子的图片。",
-    syntax: ":md-token[./token.png]",
-    props: [],
-    examples: `**展示代币：**
-:md-token[./goblin.png]
-
-代币图片自动渲染为圆形，适合战棋或卡牌中的棋子展示。`,
-    usage: "用于展示怪物代币、角色棋子、道具图标等。",
-  },
-  {
-    tag: "md-token-viewer",
-    icon: "🎨",
-    title: "代币预览组件",
-    description:
-      "使用 Three.js 在浏览器中 3D 渲染 3MF 格式的代币模型，支持旋转查看。",
-    syntax: ":md-token-viewer[./token.3mf]",
-    props: [],
-    examples: `**3D 预览模型：**
-:md-token-viewer[./dragon.3mf]
-
-支持鼠标拖拽旋转和自动旋转，从多角度查看模型细节。`,
-    usage: "用于 3D 打印前的代币模型预览。",
-  },
-  {
-    tag: "md-commander",
-    icon: "📋",
-    title: "命令追踪器",
-    description: "支持命令历史和游戏状态追踪，使用类 Emmet 语法创建追踪项。",
-    syntax: ":md-commander",
-    props: [],
-    examples: `**追踪 NPC 血量和防御：**
-\`\`\`
-track npc#john.dwarf.warrior[hp=4/4 ac=15 name="John"]
-\`\`\`
-
-**语法规则：**
-- \`#id\` 设置 ID
-- \`.class\` 添加类别
-- \`[attr=value]\` 设置属性
-
-**属性类型：**
-| 格式 | 显示 |
-|---|---|
-| x/y | 进度条 |
-| 整数 | 计数器 |
-| 文本 | 文本字段 |`,
-    usage: "用于追踪战斗中的 NPC 血量、AC、状态等游戏信息。",
-  },
-];

src/doc-entries/md-bg.md

@@ -0,0 +1,28 @@
+---
+tag: md-bg
+icon: 🖼️
+title: 背景组件
+description: 设置背景图片或纯色作为文章卡片背景，支持多种适配方式。
+syntax: ':md-bg[#ff00dd]'
+props:
+  - name: fit
+    type: cover | contain | fill | none | scale-down
+    default: cover
+    desc: 背景适配方式（仅图片时生效）
+---
+
+**设置背景图：**
+:md-bg[./images/dungeon-bg.jpg]{fit="cover"}
+
+**设置纯色背景：**
+:md-bg[#2a1a3a]
+
+:md-bg[rgb(200,50,50)]
+
+:md-bg[#ff00dd]
+
+支持图片路径或任意 CSS 颜色值（hex、rgb、颜色名等）。
+
+## 使用场景
+
+用于营造场景氛围，如地牢、森林、城镇等不同环境的背景，或纯色区分不同主题。

src/doc-entries/md-border.md

@@ -0,0 +1,36 @@
+---
+tag: md-border
+icon: 🖼️
+title: 边框组件
+description: 为文档卡片添加纯色或图片边框，支持指定边、样式和重复模式。
+syntax: ':md-border[#3b82f6]{.l .dashed}'
+props:
+  - name: width
+    type: string
+    default: 纯色 .2mm，图片 2mm
+    desc: 边框宽度
+  - name: slice
+    type: string
+    default: '"10"'
+    desc: border-image-slice（仅图片模式）
+---
+
+**纯色左边框：**
+:md-border[#3b82f6]{.l}
+
+**虚线上下边框：**
+:md-border[red]{.t .b .dashed width=".2mm"}
+
+**图片边框：**
+:md-border[./images/frame.png]{.all .round}
+
+**左右图片竖条：**
+:md-border[./images/ornament.png]{.l .r .repeat}
+
+边 class：`t` `b` `l` `r` `all`（默认）
+样式 class：`solid` `dashed` `dotted` `double`
+图片 class：`stretch` `repeat` `round` `space`
+
+## 使用场景
+
+用于装饰文档卡片，配合背景和字体营造特定风格。

src/doc-entries/md-commander.md

@@ -0,0 +1,29 @@
+---
+tag: md-commander
+icon: 📋
+title: 命令追踪器
+description: 支持命令历史和游戏状态追踪，使用类 Emmet 语法创建追踪项。
+syntax: ':md-commander'
+props: []
+---
+
+**追踪 NPC 血量和防御：**
+```
+track npc#john.dwarf.warrior[hp=4/4 ac=15 name="John"]
+```
+
+**语法规则：**
+- `#id` 设置 ID
+- `.class` 添加类别
+- `[attr=value]` 设置属性
+
+**属性类型：**
+| 格式 | 显示 |
+|---|---|
+| x/y | 进度条 |
+| 整数 | 计数器 |
+| 文本 | 文本字段 |
+
+## 使用场景
+
+用于追踪战斗中的 NPC 血量、AC、状态等游戏信息。

src/doc-entries/md-deck.md

@@ -0,0 +1,26 @@
+---
+tag: md-deck
+icon: 🃏
+title: 卡牌组件
+description: 将 CSV 数据渲染为卡牌布局，支持自定义网格和图层的排版。
+syntax: ':md-deck[./cards.csv]{grid="5x8" layers="title:1,1-5,1f8 body:1,5-8,8f3"}'
+props:
+  - name: grid
+    type: string
+    desc: 卡牌布局，格式 行x列
+  - name: layers
+    type: string
+    desc: 图层定义，格式 字段:行,列-列,字号
+---
+
+**基础卡牌：**
+:md-deck[./spells.csv]{grid="3x3"}
+
+**多层卡牌：**
+:md-deck[./cards.csv]{grid="5x8" layers="title:1,1-5,1f8 body:1,5-8,8f3"}
+
+CSV 包含 label 和显示字段列，通过图层定义控制各字段的位置和大小。
+
+## 使用场景
+
+用于法术卡、物品卡、NPC 卡等可打印的卡牌排版。

src/doc-entries/md-dice.md

@@ -0,0 +1,23 @@
+---
+tag: md-dice
+icon: 🎲
+title: 骰子组件
+description: 点击文字执行掷骰，可用于属性检定、伤害投掷等场景。
+syntax: ':md-dice[2d6+d8]{key="attack"}'
+props:
+  - name: key
+    type: string
+    desc: URL 参数标识，结果记录到 ?dice-key=15
+---
+
+**攻击检定：** :md-dice[1d20+5]{key="attack"}
+
+**伤害掷骰：** :md-dice[2d6+3]{key="damage"}
+
+**优势检定：** :md-dice[2d20k1+5]{key="advantage"}
+
+点击掷骰文字执行投掷，再次点击重置为公式。
+
+## 使用场景
+
+用于技能检定、攻击命中、伤害计算等需要随机数的场景。

src/doc-entries/md-embed.md

@@ -0,0 +1,20 @@
+---
+tag: md-embed
+icon: 📄
+title: 嵌入组件
+description: 将另一个 Markdown 文件的内容内联嵌入到当前文档中。
+syntax: ':md-embed[./rules.md#combat]'
+props: []
+---
+
+**嵌入完整文档：**
+:md-embed[./rules.md]
+
+**嵌入指定章节：**
+:md-embed[./rules.md#combat]
+
+嵌入后内容直接在当前位置显示，包括其中的表格、骰子等组件也会正常渲染。
+
+## 使用场景
+
+用于在文档中引用通用规则、重复使用的数据表格等。

src/doc-entries/md-font.md

@@ -0,0 +1,39 @@
+---
+tag: md-font
+icon: 🔤
+title: 字体组件
+description: 设置整个文档的字体和文字颜色，支持 Google Fonts、emfont 和系统本地字体三种来源。
+syntax: ':md-font[Noto Sans SC]{source="google" weight="400" color="#ff00dd"}'
+props:
+  - name: source
+    type: google | emfont | local
+    default: local
+    desc: 字体来源
+  - name: weight
+    type: string
+    default: '"400"'
+    desc: 字体粗细
+  - name: color
+    type: string
+    desc: 文字颜色（CSS 颜色值，如 #ff00dd、rgb(255,0,0)）
+---
+
+**Google 字体：**
+:md-font[Noto Sans SC]{source="google"}
+
+**Emfont 字体：**
+:md-font[Source Han Serif]{source="emfont" weight="700"}
+
+**本地字体（默认）：**
+:md-font[STSong]
+
+**设置文字颜色：**
+:md-font[Noto Sans SC]{source="google" color="#1a1a2e"}
+
+:md-font[Noto Sans SC]{source="google" weight="700" color="crimson"}
+
+字体和颜色将应用到整个文档卡片。
+
+## 使用场景
+
+用于切换文档的显示字体和文字颜色，适配不同风格需求。

src/doc-entries/md-link.md

@@ -0,0 +1,20 @@
+---
+tag: md-link
+icon: 🔗
+title: 链接组件
+description: 点击链接在当前页面内展开显示目标文章内容，支持章节定位。
+syntax: ':md-link[./rules.md#combat]'
+props: []
+---
+
+**展开完整文档：**
+:md-link[./rules.md]
+
+**展开特定章节：**
+:md-link[./rules.md#combat]
+
+点击链接即可内联展开目标内容，再次点击折叠。
+
+## 使用场景
+
+用于引用规则书章节、怪物数据、快速预览等场景。

src/doc-entries/md-pins.md

@@ -0,0 +1,35 @@
+---
+tag: md-pins
+icon: 📍
+title: 标记组件
+description: 在地图或图片上添加可编辑或固定的位置标记，支持字母或数字标签。
+syntax: ':md-pins[./images/map.png]{pins="A:30,40 B:10,30" fixed}'
+props:
+  - name: pins
+    type: string
+    default: '""'
+    desc: 标记列表，格式 "A:x,y B:x,y"
+  - name: fixed
+    type: boolean
+    default: "false"
+    desc: 固定模式（只读不可编辑）
+  - name: labelStart
+    type: string
+    default: '"A"'
+    desc: 标签起始值，支持字母或数字
+---
+
+**固定标记（只读）：**
+:md-pins[./images/battle-map.png]{pins="A:25,50 B:75,30" fixed}
+
+**可编辑标记：**
+:md-pins[./images/blank-map.png]
+
+**数字标签：**
+:md-pins[./images/dungeon.png]{labelStart="1"}
+
+非 fixed 模式下点击图片添加标记，点击标记删除。
+
+## 使用场景
+
+用于战斗地图标注、地牢房间标记、任务地点指示等。

src/doc-entries/md-table.md

@@ -0,0 +1,35 @@
+---
+tag: md-table
+icon: 📊
+title: 表格组件
+description: 将 CSV 数据转换为可切换标签页的表格，支持随机抽取和变量引用。
+syntax: ':md-table[./data.csv]{roll=true remix=true}'
+props:
+  - name: roll
+    type: boolean
+    desc: 显示随机切换按钮
+  - name: remix
+    type: boolean
+    desc: 支持 {{prop}} 引用同行其他列
+---
+
+**基础表格：**
+```markdown
+:md-table[./npcs.csv]
+```
+
+**带随机抽取：**
+```markdown
+:md-table[./encounters.csv]{roll=true}
+```
+
+**随机 + 变量引用：**
+```markdown
+:md-table[./quests.csv]{roll=true remix=true}
+```
+
+CSV 要求包含 label, body 列，可选 group 列分组。支持 YAML front matter 继承行属性。
+
+## 使用场景
+
+用于 NPC 列表、遭遇表、宝物生成、随机事件等结构化数据。

src/doc-entries/md-token-viewer.md

@@ -0,0 +1,17 @@
+---
+tag: md-token-viewer
+icon: 🎨
+title: 代币预览组件
+description: 使用 Three.js 在浏览器中 3D 渲染 3MF 格式的代币模型，支持旋转查看。
+syntax: ':md-token-viewer[./token.3mf]'
+props: []
+---
+
+**3D 预览模型：**
+:md-token-viewer[./dragon.3mf]
+
+支持鼠标拖拽旋转和自动旋转，从多角度查看模型细节。
+
+## 使用场景
+
+用于 3D 打印前的代币模型预览。

src/doc-entries/md-token.md

@@ -0,0 +1,17 @@
+---
+tag: md-token
+icon: 🪙
+title: 代币组件
+description: 展示游戏代币或棋子的图片。
+syntax: ':md-token[./token.png]'
+props: []
+---
+
+**展示代币：**
+:md-token[./goblin.png]
+
+代币图片自动渲染为圆形，适合战棋或卡牌中的棋子展示。
+
+## 使用场景
+
+用于展示怪物代币、角色棋子、道具图标等。

src/doc-entries/md-yarn-spinner.md

@@ -0,0 +1,17 @@
+---
+tag: md-yarn-spinner
+icon: 🧶
+title: 叙事线组件
+description: 展示 Yarn Spinner 格式的分支叙事结构，支持对话选择和分支。
+syntax: ':md-yarn-spinner[./story.yarn]'
+props: []
+---
+
+**加载叙事文件：**
+:md-yarn-spinner[./story.yarn]
+
+Yarn Spinner 是用于游戏对话系统的格式，支持选项、条件分支和变量。
+
+## 使用场景
+
+用于互动故事、分支对话、冒险剧本等。