# MDX (.mdx)

> 在 Markdown 中无缝嵌入 JSX 组件的超集格式，Maplen 实现可交互工程手记的媒介

- HTML: /wiki/mdx/
- Markdown: /wiki/mdx.md
- Aliases: MDX, .mdx, JSX in Markdown, 交互文档
- Updated: 2026.11.09

---

MDX（文件后缀通常为 `.mdx`）是组件化时代的 Markdown 扩展格式。它允许作者在保留传统 [Markdown (.md)](/wiki/md.md) 优雅排版语法的直接在文档正文中导入并使用 JSX 组件。

在 [Maplen](/wiki/maplen.md) 的工程手记（Nodes）中，MDX 是打破传统静态博客「只读纸面」壁垒、实现严肃工程交互的核心载体。

## 为什么在手记中引入 MDX

技术写作的最高境界，不是把结论直接灌输给读者，而是给读者提供一个**「可探索的思想沙盘」**。

通过 MDX，我们可以将复杂枯燥的技术原理转化为可交互的体验：
- **物理与电子仿真**：在 [阻尼振子与电路仿真](/nodes/oscillator-showcase.md) 中，直接嵌入带有切刀开关与交互示波器的 RLC 电路组件 ``；
- **微处理器体系结构**：在 [8 位微处理器微架构](/nodes/computer-showcase.md) 中，嵌入可单步时钟取指、译码与执行的 CPU 状态机仿真视窗 ``；
- **动态数学推导**：在 [数学公式与函数图](/nodes/math-plot-showcase.md) 中，内嵌能够动态播放泰勒级数展开与拉普拉斯逆变换公式形变的交互组件；
- **声明式图表与注记**：自由使用 `` 流程图与 `` 边栏提示。

## 同目录收纳约束（Co-located Conventions）

为了防止组件蔓延导致全局目录杂乱，Maplen 对 MDX 的组织结构制定了严格的文档约束：
1. **单篇专属组件同目录就近存放**：凡是专属于某一手记的动态组件（如 `CircuitSim.tsx`、`ComputerSim.tsx`），必须与该手记的 `.mdx` 主文件存放在同一个 `<slug>/` 文件夹内；
2. **全局组件高度克制**：只有真正跨多篇复用的基础组件（如 ``、``、``）才保留在 `src/components/` 目录中；
3. **资源内聚自治**：配图与动态组件随同手记同生同灭，重构或迁移时只需拖动整个文件夹，保持极高的模块内聚性。

关于同目录收纳与配图的最佳实践，可查阅 [同目录配图与图注规范](/nodes/image-gallery-showcase.md)。

## 官方网站与参考链接

- **官方网站**：[MDX 官方主页 (mdxjs.com)](https://mdxjs.com/)
- **技术文档**：[MDX 语法规范与组件结合指南](https://mdxjs.com/docs/what-is-mdx/)
- **开源仓库**：[GitHub - mdx-js/mdx](https://github.com/mdx-js/mdx)