MDX 组件展示：从提示框到可播放的五线谱

这是一篇可以直接操作的组件样本。每一节先给出页面效果，再说明适合放在什么内容里；写新文章时，也可以复制对应的 MDX 片段。这里展示的都是本站已经接入的能力，关于搭站过程另见从 VitePress 到 Fumadocs。

1Markdown 本身也是展示的一部分

正文支持 强调、行内代码、站内链接、引用、任务列表、GFM 表格和脚注。代码块带语言标记即可获得高亮：

type Article = { title: string; draft?: boolean };
const article: Article = { title: '一篇 MDX 文章' };

• 写清主线
• 让示例能直接运行
• 发布后继续补充新组件

例如，这页自身就是一个 MDX 文件，注册过的组件可以像 JSX 一样放进正文。¹

2Fumadocs：组织文档信息

2.1Callout：让补充信息有明确语气

写法从最短形式开始：

<Callout type="warn" title="检查路径">
  文件路径相对于 `content/`，不要写成站点 URL。
</Callout>

2.2Tabs、Steps 与 Accordions：安排阅读顺序

同一个概念有两种解释时，用标签页保留读者选择：

有先后顺序的任务，用步骤表示：

补充细节可以收起来，让正文先往前走：

2.3Files 与 TypeTable：文件树和参数表

下方文件树就是这篇文章的目录形状：

TypeTable 在说明组件接口时，比一张纯文字表更容易同时交代类型和默认值：

3Mermaid：源码和流程图放在一起

把代码块语言写为 mermaid，本站会把下面的流程渲染为图，同时保留文字源文件以便修改：

流程图适合展示分支与依赖；若需要让读者拖动点或观察连续变化，下面的几何组件更合适。

4KaTeX 与几何图：从公式到交互

行内公式可以写成 $a^2+b^2=c^2$，独立公式用双美元符号：

拖动下图中的向量端点，可以立即看到夹角变化：

<JsxGraph preset="vectors-angle" caption="拖动端点观察夹角" />

还有视野、投影、二维与三维叉积等预设；实际讲解可参照点积在游戏开发中的应用与叉积在游戏开发中的应用。复杂的静态几何配置可放在 content/ 的 JSON 中，再由 JsxGraphFromFile 读取。

5图表：Plot 与 D3

PlotChart 适合直接展示函数或数据关系。下面是本站的内置预设，角度参数可以改：

<PlotChart preset="dot-threshold" params={{ halfAngleDeg: 45 }} />

需要自己组合轴、曲线和标注时，可以使用 D3Figure 的声明式图层：

两种图表也都有 FromFile 版本，可从 content/ 下的 JSON 加载配置。图的数据变长时，把它移到文件中，正文只保留组件调用即可。

6ABCJS：会响的五线谱

短谱可以直接把 ABC 记谱写入 AbcScore。点击音符可以试听；播放时有游标和高亮，进度条也可以跳转。下面是原创的四小节上行与回落旋律：

<AbcScore caption="四小节旋律">
{`X:1
T:Four-bar sketch
M:4/4
L:1/4
Q:1/4=96
K:C
C D E F | G A B c | c B A G | F E D C |`}
</AbcScore>

较长的谱面适合独立存为 .abc，和文章放在同一目录。下面这段直接读取本页的 demo.abc：

<AbcScoreFromFile
  path="blog/(web)/mdx-component-showcase/demo.abc"
  caption="文件加载示例"
/>

谱面绘制可直接看到；播放会按需加载音色文件，因此试听时需要网络连接。实际长谱示例可看《Sweden》分析。

7ImageComparer：拖动看同一张图的变化

按住并左右拖动图片，比较同一标志的单色版和彩色版：

<ImageComparer srcBefore="/assets/logo-bl.png" srcAfter="/assets/logo-col.png" />

最适合放同一尺寸、同一取景的前后图；这里的两张图来自本站现有素材。

8写下一篇时

先让段落、标题、列表和代码块承担正文。读者需要切换视角时用 Tabs，需要看先后关系时用 Steps 或 Mermaid，需要亲手操作才能理解变化时，再放交互图或谱面。本站注册组件的入口在 components/mdx.tsx；About 页面专用组件不用于 Blog。