Markdown vs MDX：什么时候用谁（这次只讲对比示例）

如果你只看定义，很容易得到一个模糊结论：

Markdown 是写文档的
MDX 是 Markdown + JSX

但真正有价值的问题是: 同一个需求，用 Markdown 和 MDX 分别怎么写，代价分别是什么？

这篇文章不再只讲概念，直接用 4 组例子对比。

先给结论（30 秒版本）

你的内容是纯文字、图片、代码块、表格，优先 Markdown。
你需要复用组件、插入可视化、做条件或循环渲染，优先 MDX。
不是“MDX 一定更高级”，而是“MDX 让内容变成应用的一部分”。

示例 1：普通技术文章段落（Markdown 完全够用）

Markdown 写法

markdown

## 什么是缓存击穿
 
缓存击穿是指热点 key 在失效瞬间，大量请求直接打到数据库。
 
### 常见缓解方式
 
1. 热点 key 永不过期 + 主动刷新
2. 互斥锁
3. 多级缓存

MDX 写法

mdx

## 什么是缓存击穿
 
缓存击穿是指热点 key 在失效瞬间，大量请求直接打到数据库。
 
### 常见缓解方式
 
1. 热点 key 永不过期 + 主动刷新
2. 互斥锁
3. 多级缓存

对比结论

这个场景下两者几乎没有差别。
如果你没有交互、组件、动态数据需求，就用 Markdown，最稳定。

示例 2：优缺点分析卡片（MDX 开始体现价值）

Markdown 写法（通常会写成列表或表格）

markdown

## 方案分析
 
### 优点
 
- 开发效率高
- 社区成熟
 
### 缺点
 
- 包体积增长快
- 架构边界容易失控

MDX 写法（同样信息，复用组件渲染）

mdx

<SwotAnalysis
  title="使用 MDX 写技术内容"
  itemsJson='[{"label":"Strengths","children":[{"label":"复用组件","desc":"图表、卡片、流程块一次开发，多篇复用"},{"label":"表达力强","desc":"一篇文章可同时包含文档与交互"}]},{"label":"Weaknesses","children":[{"label":"复杂度上升","desc":"构建链路与运行时依赖更重"},{"label":"编辑门槛提高","desc":"作者需要理解 JSX 基础"}]}]'
/>

MDX 实际渲染效果

使用 MDX 写技术内容

Strengths

复用组件图表、卡片、流程块一次开发，多篇复用
表达力强一篇文章可同时包含文档与交互

Weaknesses

复杂度上升构建链路与运行时依赖更重
编辑门槛提高作者需要理解 JSX 基础

对比结论

Markdown 只能表达“内容本身”；
MDX 可以把“展示组件”也纳入内容系统，跨文章统一视觉和结构。

示例 3：发布流程展示（MDX 可扩展语法/组件）

Markdown 写法

markdown

## 发布流程
 
1. 写完正文
2. 本地预览
3. 运行 lint 与 build
4. 发布上线

MDX 写法（本站支持的 infographic 语法）

text

```infographic
infographic sequence-steps-simple
data
  title 博客发布流程
  items
    - label Step 1
      desc 写完正文
    - label Step 2
      desc 本地预览
    - label Step 3
      desc 运行 lint 与 build
    - label Step 4
      desc 发布上线

plaintext

 
### MDX 实际渲染效果
 
```infographic
infographic sequence-steps-simple
data
  title 博客发布流程
  items
    - label Step 1
      desc 写完正文
    - label Step 2
      desc 本地预览
    - label Step 3
      desc 运行 lint 与 build
    - label Step 4
      desc 发布上线

对比结论

Markdown 的流程是“静态文本列表”；
MDX 可以把流程转成结构化展示组件，信息密度更高。

示例 4：同一份数据批量渲染（MDX 支持逻辑）

Markdown 写法

markdown

## 发布前检查清单
 
- [x] Front matter 完整
- [x] 标题层级正确
- [ ] 外链可访问
- [ ] 图片已压缩

MDX 写法

mdx

## 发布前检查清单
 
<ul>
  {[
    { name: 'Front matter 完整', done: true },
    { name: '标题层级正确', done: true },
    { name: '外链可访问', done: false },
    { name: '图片已压缩', done: false },
  ].map((item) => (
    <li key={item.name}>
      [{item.done ? 'x' : ' '}] {item.name}
    </li>
  ))}
</ul>

MDX 实际渲染效果

对比结论

Markdown 需要手写每一行；
MDX 可以基于数据生成内容，尤其适合教程步骤、参数矩阵、版本变更列表。

什么时候该用 Markdown，什么时候该用 MDX

场景	建议
个人博客、日常技术记录、README	Markdown 优先
文档站需要统一卡片/告警/流程组件	MDX 更合适
交互式教程、可视化内容、动态渲染	MDX 必选
多人协作且作者不懂 JSX	Markdown 更稳妥

最后一句话

内容像“文章”，用 Markdown。
内容像“产品界面的一部分”，用 MDX。

不要为了“看起来高级”强行上 MDX。
只有当组件复用和动态表达真的带来收益时，MDX 才值得。

参考资料

Markdown vs MDX：什么时候用谁（这次只讲对比示例）

如果你只看定义，很容易得到一个模糊结论：

Markdown 是写文档的
MDX 是 Markdown + JSX

但真正有价值的问题是: 同一个需求，用 Markdown 和 MDX 分别怎么写，代价分别是什么？

这篇文章不再只讲概念，直接用 4 组例子对比。

先给结论（30 秒版本）

你的内容是纯文字、图片、代码块、表格，优先 Markdown。
你需要复用组件、插入可视化、做条件或循环渲染，优先 MDX。
不是“MDX 一定更高级”，而是“MDX 让内容变成应用的一部分”。

示例 1：普通技术文章段落（Markdown 完全够用）

Markdown 写法

markdown

## 什么是缓存击穿
 
缓存击穿是指热点 key 在失效瞬间，大量请求直接打到数据库。
 
### 常见缓解方式
 
1. 热点 key 永不过期 + 主动刷新
2. 互斥锁
3. 多级缓存

MDX 写法

mdx

## 什么是缓存击穿
 
缓存击穿是指热点 key 在失效瞬间，大量请求直接打到数据库。
 
### 常见缓解方式
 
1. 热点 key 永不过期 + 主动刷新
2. 互斥锁
3. 多级缓存

对比结论

这个场景下两者几乎没有差别。
如果你没有交互、组件、动态数据需求，就用 Markdown，最稳定。

示例 2：优缺点分析卡片（MDX 开始体现价值）

Markdown 写法（通常会写成列表或表格）

markdown

## 方案分析
 
### 优点
 
- 开发效率高
- 社区成熟
 
### 缺点
 
- 包体积增长快
- 架构边界容易失控

MDX 写法（同样信息，复用组件渲染）

mdx

<SwotAnalysis
  title="使用 MDX 写技术内容"
  itemsJson='[{"label":"Strengths","children":[{"label":"复用组件","desc":"图表、卡片、流程块一次开发，多篇复用"},{"label":"表达力强","desc":"一篇文章可同时包含文档与交互"}]},{"label":"Weaknesses","children":[{"label":"复杂度上升","desc":"构建链路与运行时依赖更重"},{"label":"编辑门槛提高","desc":"作者需要理解 JSX 基础"}]}]'
/>

MDX 实际渲染效果

使用 MDX 写技术内容

Strengths

复用组件图表、卡片、流程块一次开发，多篇复用
表达力强一篇文章可同时包含文档与交互

Weaknesses

复杂度上升构建链路与运行时依赖更重
编辑门槛提高作者需要理解 JSX 基础

对比结论

Markdown 只能表达“内容本身”；
MDX 可以把“展示组件”也纳入内容系统，跨文章统一视觉和结构。

示例 3：发布流程展示（MDX 可扩展语法/组件）

Markdown 写法

markdown

## 发布流程
 
1. 写完正文
2. 本地预览
3. 运行 lint 与 build
4. 发布上线

MDX 写法（本站支持的 infographic 语法）

text

```infographic
infographic sequence-steps-simple
data
  title 博客发布流程
  items
    - label Step 1
      desc 写完正文
    - label Step 2
      desc 本地预览
    - label Step 3
      desc 运行 lint 与 build
    - label Step 4
      desc 发布上线

plaintext

 
### MDX 实际渲染效果
 
```infographic
infographic sequence-steps-simple
data
  title 博客发布流程
  items
    - label Step 1
      desc 写完正文
    - label Step 2
      desc 本地预览
    - label Step 3
      desc 运行 lint 与 build
    - label Step 4
      desc 发布上线

对比结论

Markdown 的流程是“静态文本列表”；
MDX 可以把流程转成结构化展示组件，信息密度更高。

示例 4：同一份数据批量渲染（MDX 支持逻辑）

Markdown 写法

markdown

## 发布前检查清单
 
- [x] Front matter 完整
- [x] 标题层级正确
- [ ] 外链可访问
- [ ] 图片已压缩

MDX 写法

mdx

## 发布前检查清单
 
<ul>
  {[
    { name: 'Front matter 完整', done: true },
    { name: '标题层级正确', done: true },
    { name: '外链可访问', done: false },
    { name: '图片已压缩', done: false },
  ].map((item) => (
    <li key={item.name}>
      [{item.done ? 'x' : ' '}] {item.name}
    </li>
  ))}
</ul>

MDX 实际渲染效果

对比结论

Markdown 需要手写每一行；
MDX 可以基于数据生成内容，尤其适合教程步骤、参数矩阵、版本变更列表。

什么时候该用 Markdown，什么时候该用 MDX

场景	建议
个人博客、日常技术记录、README	Markdown 优先
文档站需要统一卡片/告警/流程组件	MDX 更合适
交互式教程、可视化内容、动态渲染	MDX 必选
多人协作且作者不懂 JSX	Markdown 更稳妥

最后一句话

内容像“文章”，用 Markdown。
内容像“产品界面的一部分”，用 MDX。

不要为了“看起来高级”强行上 MDX。
只有当组件复用和动态表达真的带来收益时，MDX 才值得。