建议 WPS Markdown 引入 MDX 组件功能

引言

WPS 正式上线 Markdown格式支持，这一功能填补了国内主流办公软件在原生 Markdown 支持上的空白。然而，Markdown 自身存在一个长期未解决的结构性短板：缺乏组件化能力。标准 Markdown 只能表达静态文本结构（标题、段落、列表、代码块），无法嵌入可交互的 UI 组件、动态图表或自定义渲染逻辑。随着技术文档、AI 生成内容和知识管理对交互性要求的提升，这一限制日益突出。

MDX（Markdown for JSX）正是在这一背景下产生的技术方案。

一、MDX 是什么

MDX 是一种开源的书写格式（GitHub: mdx-js/mdx，MIT 协议），允许在 Markdown 文档中无缝嵌入 JSX 代码，同时支持 ESM 模块的导入与导出。MDX 将 Markdown 的简洁性与 JSX 的组件化能力融合在同一文件中，使"内容"与"交互"不再分离。

MDX 项目的 GitHub 仓库已获得超过 19,500 个 Star，核心编译器包 @mdx-js/mdx 的月下载量超过 2,400 万次。其官方站点 mdxjs.com 将其定位为"Markdown for the component era"——组件时代的 Markdown。

MDX 与 Markdown 的关系

MDX 是 Markdown 的严格超集。标准 Markdown 的全部语法（标题、段落、列表、代码块、引用、表格、链接、图片等）在 MDX 中均可正常使用。MDX 在此基础上增加了两项核心扩展能力：

1. JSX 嵌入：在文档中直接编写 JSX 表达式和组件标签

2. ESM 模块：通过 import/export 语句导入外部组件、导出文档元数据

二、MDX 的核心能力

2.1 组件嵌入与导入

MDX 最基础的能力是在 Markdown 中嵌入 JSX 组件。以下代码片段展示了这一特性：

import { Chart } from './snowfall.js'
export const year = 2023

# Last year's snowfall

In {year}, the snowfall was above average.
It was followed by a warm spring which caused
flood conditions in many of the nearby rivers.

<Chart year={year} color="#fcb32c" />

上述代码中，import 语句引入了一个外部图表组件，export 导出了文档级别的变量，Markdown 正文与 JSX 组件标签自然混排。编译后，整个文件被转换为标准的 JavaScript 模块，可在任何支持 JSX 的框架中运行。

2.2 自定义组件映射

MDX 允许为 Markdown 的每个语法元素指定对应的渲染组件。例如，可以将所有一级标题映射为自定义的 Heading 组件，将表格映射为带有排序功能的 DataTable 组件：

const components = {
  h1: Heading,
  h2: SubHeading,
  table: DataTable,
  code: CodeBlock
}

通过这种方式，文档的结构语义（"这是一个标题"、"这是一个表格"）与视觉表现之间实现了完全解耦。内容创作者只需关注"写什么"，而渲染逻辑由组件体系统一管控。

2.3 MDX 文件作为组件复用

MDX 文件本身也可以被当作组件导入。这意味着一个 MDX 文档可以嵌入另一个 MDX 文档，实现内容的模块化和复用。这一特性在大型文档站点（如技术文档、知识库）中具有显著的实际价值——团队可以将公共的说明段落、警告信息、法律声明等封装为独立的 MDX 组件，在各文档中按需引用。

2.4 v3 新特性

MDX v3（2023 年 10 月发布）引入了多项重要改进：

• Top-level await：支持在 MDX 中使用 await 语法（需运行时框架配合），允许在文档内执行异步数据加载

• ES2024 语法支持：MDX 内容区可使用最新的 ECMAScript 语法特性

• 相邻 JSX 和表达式块：允许多个 JSX 标签或表达式在同一位置连续书写，不受传统 Markdown 段落分隔规则的约束

v3 同时移除了对 Node.js 16 以下版本的支持，并清理了多个已废弃的 API，整体架构更加现代化。

三、生态与兼容性

3.1 插件体系

MDX 基于统一的 content 数据处理管道构建，天然兼容 remark（Markdown 处理插件生态）和 rehype（HTML 处理插件生态）。这意味着 Markdown 社区积累的数百个插件可直接用于 MDX：

MDX 自身的编译流程为：MDX 源码 → remark 解析 → remark 插件处理 → rehype 转换 → rehype 插件处理 → JS 模块输出。这一管道完全可编程，任何环节都可以插入自定义逻辑。

3.2 框架与构建工具支持

MDX 已实现主流技术栈的全面覆盖：

JSX 框架：React、Preact、Vue（通过 @mdx-js/vue 或 MDX 的非 React 运行时）、Emotion、Styled Components 等。

构建工具：Webpack（@mdx-js/loader）、Rollup（@mdx-js/rollup）、esbuild（@mdx-js/esbuild）、Vite（通过 Rollup 插件或 esbuild loader）、Parcel（parcel-transformer-mdx）、Bun 原生支持。

文档框架：Docusaurus、Nextra、Storybook、Fumadocs、VitePress（社区方案）、Astro 等。其中 Docusaurus 的 Markdown 特性文档明确指出"The MDX compiler transforms Markdown files to React components, and allows you to use JSX in your Markdown content"。

3.3 运行时选择

MDX v3 提供两种运行时方案：

• 函数体运行时（Function Body Runtime）：编译后的 MDX 生成标准 JS 函数，无额外运行时依赖，性能最优，适用于生产环境

• 自动运行时（Automatic Runtime）：自动注入 JSX 转换辅助函数，开发者无需手动配置 JSX pragma

两种方案均无框架锁定，可自由搭配 React、Preact 等库。

四、MDX 对 WPS 的价值分析

4.1 技术文档与组件库文档场景

技术文档是 MDX 最成熟的应用领域。Docusaurus（Meta/Facebook 开源的文档框架）、Nextra（Vercel 出品的文档框架）、Storybook（组件文档与开发工具）等主流方案均已将 MDX 作为默认的文档编写格式。React 官方文档（beta.reactjs.org）同样采用 MDX 构建，利用自定义组件实现了交互式代码示例、可编辑的 Playground、API 参数表格等复杂文档元素。

WPS 若支持 MDX，其技术文档场景将获得质的提升：开发者可以在文档中嵌入可运行的代码示例、交互式 API 演示和动态数据表格，而无需借助外部链接或截图。

4.2 AI 内容承接场景

2026 年 5 月，Anthropic Claude Code 团队的工程师 Thariq Shihipar 发布了一篇题为《Using Claude Code: The Unreasonable Effectiveness of HTML》的文章，在 X 平台获得超过 950 万次浏览。他在文中系统性地论述了一个观点：当 AI Agent 能够处理越来越复杂的任务时，HTML 正在取代 Markdown，成为 AI 交付给人类更合适的输出格式。

Markdown 的核心设计目标是"写起来像纯文本，渲染出来像 HTML"——它本身就不追求成为最终呈现层。而 AI 正在重新定义"最终呈现"的含义。当用户要求 AI 生成一份交互式数据看板、一个可运行的原型页面、一份包含嵌入式图表的可视化报告时，Markdown 无法承载这些需求，HTML 却天然适配。

Thariq 在文章中对比了两种格式的差异。Markdown 在超过 100 行之后阅读体验急剧下降，而 HTML 可以通过标签页、插图、锚点链接等方式组织长文档的结构，使其更易导航。HTML 支持响应式布局、CSS 样式控制、SVG 矢量图形和 Canvas 画布，这意味着 AI 的产出不再受限于纯文本排版，而是可以包含丰富的视觉和交互元素。

前特斯拉 AI 总监、知名 AI 研究者 Andrej Karpathy 随后转发了这篇文章并补充了他的判断："音频是大语言模型最好的输入，视觉是最好的输出"。

主流大语言模型产品正逐渐扩大 HTML 输出的比重。ChatGPT 的 Canvas 功能支持将 AI 生成内容直接渲染为可编辑的网页；Claude 的 Artifacts 机制将代码、文档和可视化内容以独立的 HTML 容器呈现；DeepSeek 在用户要求生成游戏或工具时，直接输出可运行的 HTML 文件。这些产品实践的共同方向是：AI 的输出正在从"给人类看一段文字"进化为"给人类交付一个可交互的制品"。

WPS 作为用户与 AI 产出之间的关键枢纽，需要具备承接 HTML 格式内容的能力——不仅是打开和预览，还包括编辑、批注和再分发。在 Markdown 与 HTML 之间，MDX 恰好提供了一个关键的中间地带——它以 Markdown 的简洁语法为基底，同时支持通过 JSX 引入 HTML 级的表达力和交互能力。对于需要保留 Markdown 编写效率、同时逐步引入富交互内容的场景，MDX 是比直接跳转到 HTML 更平滑的过渡路径。

4.3 渐进式实施路径

从工程实现角度，WPS 可采用渐进式策略引入 MDX：

• 第一阶段：支持 MDX 文件的打开与渲染预览，复用 WPS 现有的 Markdown 渲染管线，增加 JSX 语法识别与安全沙箱组件渲染

• 第二阶段：支持 MDX 文件的编辑与保存，提供内置组件库（图表、代码块、表格、折叠面板等）

• 第三阶段：开放 MDX 组件扩展机制，允许用户或第三方开发自定义组件

这一路径的核心挑战在于安全沙箱的构建——MDX 允许执行任意 JavaScript 代码，在办公软件场景中必须通过严格的沙箱隔离机制确保安全性。可参考方案包括：基于 iframe 的隔离渲染、受限的组件白名单机制、或编译时的 AST 级静态分析。