# MDX (.mdx)

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

- Site: https://maplen.top/
- Page: https://maplen.top/wiki/mdx/
- LLM: https://maplen.top/wiki/mdx/llms.txt
- Author: 红枫 (Maple)
- Audience: AI agents / LLM tools
- Updated: 2026.11.09
- Markdown: https://maplen.top/wiki/mdx.md

## Content

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)

## Backlinks

- [脚本交互与代码展示：8 位微处理器动态演示](https://maplen.top/nodes/computer-showcase/llms.txt): 基于网站的 JS 脚本组件支持，构建 8 位 CPU 状态机可视化演示，并测试代码高亮、复制与悬停黑块功能
- [从源码到边缘：基于 GitHub 与 Cloudflare Workers 的全自动持续交付](https://maplen.top/nodes/deployment-showcase/llms.txt): 摒弃沉重的动态服务器与数据库，解析 Maplen 的静态技术路线选型、Git 源码资产沉淀，以及基于 Cloudflare Workers 静态资产网络的全自动持续交付流水线
- [纸、墨与四色：我为什么这样设计 Maplen](https://maplen.top/nodes/design-system/llms.txt): 从一张纸、四种语气到统一模板与局部嵌入，这是我为 Maplen 确立的建站理念、核心架构与设计手记
- [笔墨与纸面：Maplen 的排版美学与文本地基](https://maplen.top/nodes/markdown-showcase/llms.txt): 从字形微调、行间呼吸到 Wiki 双向链接与微观句子锚点，为长篇沉浸阅读筑牢坚实的地基
- [架构图与系统流向：Maplen 是如何运转的](https://maplen.top/nodes/architecture-showcase/llms.txt): 从 4N 正交体系到静态优先流水线，用 Mermaid 图表全景解析我为 Maplen 搭建的底层逻辑
- [Astro](https://maplen.top/wiki/astro/llms.txt): 现代静态优先、内容驱动的 Web 框架，Maplen 的基座构建引擎与孤岛架构运行时
- [Markdown (.md)](https://maplen.top/wiki/md/llms.txt): 轻量级纯文本标记语言与文件格式，Maplen 沉浸式阅读与文字交付的基石
- [Mermaid](https://maplen.top/wiki/mermaid/llms.txt): 基于文本的声明式图表绘制语法，Maplen 架构拓扑与状态机可视化的内嵌引擎