Elytra
网站

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

一页看完本站已接入的 Fumadocs 组件、Mermaid、KaTeX、ABCJS 谱面和交互式图表，并附可复用的 MDX 写法。

站务
GPT-6
mdxfumadocsmermaidabcjscomponents

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

想表达什么可以先选
补充说明、风险或结论Callout
并列视角、操作流程、可折叠细节Tabs、Steps、Accordions
目录结构、参数说明Files、TypeTable
关系和流程Mermaid
数学表达与可拖动的几何图KaTeX、JsxGraph
数据曲线与定制图层PlotChart、D3Figure
五线谱和试听AbcScore、AbcScoreFromFile
两张图之间的变化ImageComparer

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

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

type Article = { title: string; draft?: boolean };
const article: Article = { title: '一篇 MDX 文章' };
  • 写清主线
  • 让示例能直接运行
  • 发布后继续补充新组件

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

2Fumadocs：组织文档信息

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

背景

info 适合放阅读前需要知道的上下文。

容易踩的坑

warn 用于提醒读者检查条件，例如路径是否相对于 content/。

错误后果

error 适合说明一个操作会造成什么明确的问题。

实践判断

idea 可以承载作者的取舍或建议。

得到的结果

success 适合在一段推导或步骤结束时收束结论。

写法从最短形式开始：

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

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

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

把横向比较放在同一位置，读者可以切换视角。

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

在专题目录下写 .mdx，为页面填写 frontmatter。
在该专题的 meta.json 中登记 slug。
运行构建，检查实际渲染和链接。

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

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

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

index.mdx
demo.abc
meta.json

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

Prop

Type

3Mermaid：代表性图表

本站默认使用 Pele。右键或长按任意图表，可以切换到 Beautiful Mermaid 对比，选择会自动保存。复杂图可以使用右上角按钮放大或弹窗查看。

这里保留几张较完整的代表作，官方示例保留英文与原始结构，数据仅用于展示。全部图种、更多布局与来源说明见 Mermaid 图集。

3.1Git：多分支开发与合并

来源：Pele Examples。

Loading diagram…

Mermaid 源代码

---
config:
  logLevel: 'debug'
  theme: 'neutral'
---
      gitGraph
        commit
        branch hotfix
        checkout hotfix
        commit
        branch develop
        checkout develop
        commit id:"ash" tag:"abc"
        branch featureB
        checkout featureB
        commit type:HIGHLIGHT
        checkout main
        checkout hotfix
        commit type:NORMAL
        checkout develop
        commit type:REVERSE
        checkout featureB
        commit
        checkout main
        merge hotfix
        checkout featureB
        commit
        checkout develop
        branch featureA
        commit
        checkout develop
        merge hotfix
        checkout featureA
        commit
        checkout featureB
        commit
        checkout develop
        merge featureA
        branch release
        checkout release
        commit
        checkout main
        commit
        checkout release
        merge main
        checkout develop
        merge release

可选择文字复制；按 Esc 或点击空白处关闭。

3.2CQRS：命令与查询分离

本站补充的完整架构示意：命令侧写入事件，投影更新读模型，查询侧读取独立存储。

Loading diagram…

Mermaid 源代码

flowchart LR
  User[Web / Mobile Client]
  subgraph Commands[Command side]
    API[Command API]
    Auth{Authorization}
    Handler[Command Handler]
    Aggregate[Order Aggregate]
    Rules{Business Rules}
    Store[(Event Store)]
    Outbox[(Transactional Outbox)]
    API --> Auth
    Auth -->|allowed| Handler
    Auth -->|denied| Rejected[Reject Request]
    Handler --> Aggregate --> Rules
    Rules -->|valid| Store
    Rules -->|invalid| Rejected
    Store --> Outbox
  end
  subgraph Events[Event distribution]
    Relay[Outbox Relay]
    Bus[Event Bus]
    Retry[Retry Queue]
    Dead[(Dead Letter Queue)]
    Relay --> Bus
    Bus -->|temporary failure| Retry
    Retry -->|retry| Bus
    Retry -->|limit exceeded| Dead
  end
  subgraph Queries[Query side]
    Projection[Order Projection]
    Search[Index Projection]
    ReadDB[(Read Database)]
    Index[(Search Index)]
    QueryAPI[Query API]
    Cache[(Response Cache)]
    Projection --> ReadDB
    Search --> Index
    QueryAPI --> ReadDB
    QueryAPI --> Index
    QueryAPI <-->|cache| Cache
  end
  User -->|PlaceOrder| API
  Outbox --> Relay
  Bus -->|OrderPlaced| Projection
  Bus -->|OrderPlaced| Search
  Bus -->|OrderPlaced| Email[Notification Worker]
  User -->|GetOrder / SearchOrders| QueryAPI
  QueryAPI -->|read model| User
  Store -. replay events .-> Projection

可选择文字复制；按 Esc 或点击空白处关闭。

3.3Mindmap：多级知识结构

来源：Pele Examples。

Loading diagram…

Mermaid 源代码

mindmap
  root((mindmap))
    Origins
      Long history
      ::icon(fa fa-book)
      Popularization
        British popular psychology author Tony Buzan
    Research
      On effectiveness<br/>and features
      On Automatic creation
        Uses
            Creative techniques
            Strategic planning
            Argument mapping
    Tools
      Pen and paper
      Mermaid

可选择文字复制；按 Esc 或点击空白处关闭。

3.4Gantt：任务、依赖与里程碑

来源：Pele Examples。

Loading diagram…

Mermaid 源代码

gantt
    dateFormat  YYYY-MM-DD
    title       Adding GANTT diagram functionality to mermaid
    excludes    weekends
    %% (`excludes` accepts specific dates in YYYY-MM-DD format, days of the week ("sunday") or "weekends", but not the word "weekdays".)

    section A section
    Completed task            :done,    des1, 2014-01-06,2014-01-08
    Active task               :active,  des2, 2014-01-09, 3d
    Future task               :         des3, after des2, 5d
    Future task2              :         des4, after des3, 5d

    section Critical tasks
    Completed task in the critical line :crit, done, 2014-01-06,24h
    Implement parser and jison          :crit, done, after des1, 2d
    Create tests for parser             :crit, active, 3d
    Future task in critical line        :crit, 5d
    Create tests for renderer           :2d
    Add to mermaid                      :until isadded
    Functionality added                 :milestone, isadded, 2014-01-25, 0d

    section Documentation
    Describe gantt syntax               :active, a1, after des1, 3d
    Add gantt diagram to demo page      :after a1  , 20h
    Add another diagram to demo page    :doc1, after a1  , 48h

    section Last section
    Describe gantt syntax               :after doc1, 3d
    Add gantt diagram to demo page      :20h
    Add another diagram to demo page    :48h

可选择文字复制；按 Esc 或点击空白处关闭。

3.5Chart：柱形与折线

来源：Pele Examples。

Loading diagram…

Mermaid 源代码

---
config:
    xyChart:
        width: 900
        height: 600
        showDataLabel: true
    themeVariables:
        xyChart:
            titleColor: "#ff0000"
---
xychart
    title "Sales Revenue"
    x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
    y-axis "Revenue (in $)" 4000 --> 11000
    bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
    line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]

可选择文字复制；按 Esc 或点击空白处关闭。

3.6Pie：分类占比

来源：Pele Examples。

Loading diagram…

Mermaid 源代码

---
config:
  pie:
    textPosition: 0.5
    donutHole: 0.2
    highlightSlice: Potassium
  themeVariables:
    pieOuterStrokeWidth: "5px"
---
pie showData
    title Key elements in Product X
    "Calcium" : 42.96
    "Potassium" : 50.05
    "Magnesium" : 10.01
    "Iron" :  5

可选择文字复制；按 Esc 或点击空白处关闭。

3.7Sankey：完整能源网络

来源：Pele Examples。

Loading diagram…

Mermaid 源代码

---
config:
  sankey:
    showValues: false
    height: 800
---
sankey

Agricultural 'waste',Bio-conversion,124.729
Bio-conversion,Liquid,0.597
Bio-conversion,Losses,26.862
Bio-conversion,Solid,280.322
Bio-conversion,Gas,81.144
Biofuel imports,Liquid,35
Biomass imports,Solid,35
Coal imports,Coal,11.606
Coal reserves,Coal,63.965
Coal,Solid,75.571
District heating,Industry,10.639
District heating,Heating and cooling - commercial,22.505
District heating,Heating and cooling - homes,46.184
Electricity grid,Over generation / exports,104.453
Electricity grid,Heating and cooling - homes,113.726
Electricity grid,H2 conversion,27.14
Electricity grid,Industry,342.165
Electricity grid,Road transport,37.797
Electricity grid,Agriculture,4.412
Electricity grid,Heating and cooling - commercial,40.858
Electricity grid,Losses,56.691
Electricity grid,Rail transport,7.863
Electricity grid,Lighting & appliances - commercial,90.008
Electricity grid,Lighting & appliances - homes,93.494
Gas imports,Ngas,40.719
Gas reserves,Ngas,82.233
Gas,Heating and cooling - commercial,0.129
Gas,Losses,1.401
Gas,Thermal generation,151.891
Gas,Agriculture,2.096
Gas,Industry,48.58
Geothermal,Electricity grid,7.013
H2 conversion,H2,20.897
H2 conversion,Losses,6.242
H2,Road transport,20.897
Hydro,Electricity grid,6.995
Liquid,Industry,121.066
Liquid,International shipping,128.69
Liquid,Road transport,135.835
Liquid,Domestic aviation,14.458
Liquid,International aviation,206.267
Liquid,Agriculture,3.64
Liquid,National navigation,33.218
Liquid,Rail transport,4.413
Marine algae,Bio-conversion,4.375
Ngas,Gas,122.952
Nuclear,Thermal generation,839.978
Oil imports,Oil,504.287
Oil reserves,Oil,107.703
Oil,Liquid,611.99
Other waste,Solid,56.587
Other waste,Bio-conversion,77.81
Pumped heat,Heating and cooling - homes,193.026
Pumped heat,Heating and cooling - commercial,70.672
Solar PV,Electricity grid,59.901
Solar Thermal,Heating and cooling - homes,19.263
Solar,Solar Thermal,19.263
Solar,Solar PV,59.901
Solid,Agriculture,0.882
Solid,Thermal generation,400.12
Solid,Industry,46.477
Thermal generation,Electricity grid,525.531
Thermal generation,Losses,787.129
Thermal generation,District heating,79.329
Tidal,Electricity grid,9.452
UK land based bioenergy,Bio-conversion,182.01
Wave,Electricity grid,19.013
Wind,Electricity grid,289.366

可选择文字复制；按 Esc 或点击空白处关闭。

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

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

a⋅b=∥a∥ ∥b∥cos⁡θ\mathbf a\cdot\mathbf b=\|\mathbf a\|\,\|\mathbf b\|\cos\theta

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

JsxGraph：拖动端点，观察两向量夹角
<JsxGraph preset="vectors-angle" caption="拖动端点观察夹角" />

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

5图表：Plot 与 D3

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

Observable Plot：点积视野阈值
<PlotChart preset="dot-threshold" params={{ halfAngleDeg: 45 }} />

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

D3Figure：抛物线和三个采样点

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

6ABCJS：会响的五线谱

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

C 大调示例：四小节旋律，可点击音符试听

正在加载钢琴音色…

<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：拖动看同一张图的变化

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

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

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

8写下一篇时

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

注释

  1. 本站文章从 VitePress 到 Fumadocs介绍了 content/ 文件、MDX 与组件在写作流程中的关系；这里的说法对应本站当前实现。 ↩

CONTINUE EXPLORING

沿着这篇文章继续

在地图中查看
主题相近Pele：重新实现 Mermaid 的高性能图表渲染引擎主题相近主题相近从 VitePress 到 Fumadocs主题相近主题相近Mermaid 图集：用 Pele 展示完整图表主题相近

前端框架的兴衰：为什么 React 成为主流？

从 jQuery、AngularJS 到 React、Vue、Svelte 与 Astro：回顾现代前端的演变，解释 React 的技术创新、历史时机与生态网络效应，以及它领先之后的代价。

Mermaid 图集：用 Pele 展示完整图表

从 Pele 官方 Examples 选取完整示例，展示 Git、时序、C4、状态机、思维导图、甘特图、桑基图等全部图种，并补充一张 CQRS 架构图。

评论与交流

在 GitHub 查看讨论

欢迎补充、提问，或分享不同的看法。使用 GitHub 账号登录后即可评论。

On this page

1Markdown 本身也是展示的一部分2Fumadocs：组织文档信息2.1Callout：让补充信息有明确语气2.2Tabs、Steps 与 Accordions：安排阅读顺序2.3Files 与 TypeTable：文件树和参数表3Mermaid：代表性图表3.1Git：多分支开发与合并3.2CQRS：命令与查询分离3.3Mindmap：多级知识结构3.4Gantt：任务、依赖与里程碑3.5Chart：柱形与折线3.6Pie：分类占比3.7Sankey：完整能源网络4KaTeX 与几何图：从公式到交互5图表：Plot 与 D36ABCJS：会响的五线谱7ImageComparer：拖动看同一张图的变化8写下一篇时注释