革命性的写作：MDX 让你的 Markdown 全面动起来

1. MDX

MDX 是一种标记语法，它结合了 Markdown（一种流行的文本到 HTML 的转换工具）和 JSX（React 中用于描述 UI 组件的语法扩展）。MDX 允许你在 Markdown 文档中直接写入 JSX，这意味着你可以在 Markdown 内容中嵌入 React 组件。

MDX 的主要目标是使得内容作者能够在文档中轻松地加入交互性和动态性，而不需要完全转向使用复杂的编程环境。这样，作者可以利用 Markdown 的简易性，并通过嵌入 React 组件来增强内容的表现力和功能性。

例如，你可以在 MDX 文件中这样使用：

# 这是一个标题

这里是正常的 Markdown 文本。

<SomeReactComponent prop="value" />

以上是一个 React 组件，它将被渲染为与其他 Markdown 内容一起的一部分。

MDX 通常在静态站点生成器（如 Gatsby 或 Next.js）和文档工具中使用，这些工具利用 React 来构建网站和应用程序。MDX 通过提供一种方式来混合传统的 Markdown 文档和现代的 Web 应用开发技术，为编写具有高度自定义性和交互性内容的作者和开发者提供了便利。

2. 诞生背景

MDX 的诞生背景是基于对在 Markdown 文档中无缝集成动态内容和组件的需求。Markdown 自从被创造以来，就因其易于阅读和写作的简洁语法而受到广泛欢迎。它允许作者以纯文本格式编写内容，然后将其转换成格式化的 HTML，非常适合编写文档和博客文章等。

然而，随着 web 技术的发展，尤其是 React 等现代 JavaScript 库的兴起，开发者和内容创作者对于在文档中嵌入更丰富的交互式组件的需求日益增长。传统的 Markdown 在这方面受到限制，因为它主要是一个静态标记语言，不支持直接嵌入这样的动态内容。

MDX 应运而生的目的是为了解决这个问题。通过将 Markdown 与 JSX 结合，MDX 允许开发者和作者在 Markdown 文档中直接使用 React 组件，从而实现以下目标：

1. 增强交互性：通过嵌入可交互的 React 组件，使得文档可以包含表单、图表、轮播图等动态元素。
2. 提升表现力：React 组件可以用来展示复杂的布局和风格，比纯 Markdown 文本更丰富。
3. 提高复用性：可以在不同的 MDX 文档中重用相同的组件，提高开发效率。
4. 平滑的学习曲线：内容创作者可以继续使用他们熟悉的 Markdown 语法编写内容，同时逐步学习和添加 JSX/React 组件的使用。

MDX 的设计意图是保持 Markdown 的简单性和易用性，同时赋予它扩展的能力，使其能够适应现代 web 开发的需求。这样做既满足了技术用户的需要，也为非技术用户提供了一个相对容易上手的途径去创建更丰富和动态的内容。

3. 适用场景

MDX 的主要使用场景包括但不限于以下几个方面：

1. 技术文档：对于编写技术文档的开发者来说，MDX 提供了一个在文档中直接嵌入演示代码组件、交互式示例和实时编辑器的便捷方式。

2. 博客平台：博客作者可以使用 MDX 来创建更丰富的内容，例如嵌入视频、幻灯片、图表或其他自定义组件，从而提高用户的阅读体验。

3. 教育材料：教育和在线学习平台可以利用 MDX 来创建互动式教程和练习，使学习过程更加引人入胜。

4. 营销与演示：MDX 可以被用来构建营销页面、产品演示或展示页面，通过动态组件来更好地呈现信息和吸引用户。

5. 个人和企业网站：在个人或企业网站中，MDX 提供了一种简化的方式来管理站点内容，同时加入必要的互动性特性。

6. 电子书籍和在线出版：出版商可以使用 MDX 来加入互动图表、注释或其他多媒体内容，让阅读体验更加丰富。

7. 产品说明和帮助中心：利用 MDX，可以在帮助文档中嵌入常见问题解答（FAQ）组件、支持表单或其他有助于用户理解产品的自定义组件。

8. 快速原型设计和设计系统文档：设计师和前端开发者可以使用 MDX 来快速创建和共享设计元素的原型，或者构建包含实际组件的设计系统文档。

9. 数据可视化：数据科学家和分析师可以利用 MDX 嵌入图表和数据可视化组件，以提供互动式的数据解读。

10. 会议和演讲：演讲者和会议主持人可以使用 MDX 来制作包含互动性元素的幻灯片和演示文稿。

由于 MDX 结合了 Markdown 的易用性和 React 组件的强大功能，它适用于任何需要在文本内容中嵌入动态或交互式元素的场合。MDX 既能帮助程序员提高开发效率，也让内容创作者更容易制作丰富多彩的内容。

4. 安装使用

要安装和使用 MDX，您需要首先设置一个支持 React 的项目环境，例如使用 Create React App 或者一个像 Next.js 或 Gatsby 这样的静态站点生成器。以下是一个基本的安装和使用 MDX 的指南：

1. 安装 MDX

首先，您需要在项目中安装 @mdx-js/mdx 和 @mdx-js/react 这两个 npm 包。打开终端，然后运行以下命令：

npm install @mdx-js/mdx @mdx-js/react

或者，如果您使用的是 yarn：

yarn add @mdx-js/mdx @mdx-js/react

2. 配置加载器

如果您正在使用像 Webpack 这样的模块打包工具，您需要配置一个加载器来处理 MDX 文件。例如，如果您使用的是 Babel 和 Webpack，您可能需要安装 babel-loader 和 @babel/core：

npm install babel-loader @babel/core --save-dev

然后，配置 Webpack 的 module.rules 来告诉它如何处理 .mdx 文件：

// webpack.config.js
module.exports = {
  // ...
  module: {
    rules: [
      {
        test: /\.mdx?$/,
        use: ["babel-loader", "@mdx-js/loader"],
      },
      // 其他 loaders...
    ],
  },
  // ...
};

3. 在 React 项目中使用 MDX

现在您可以在 React 组件中导入和使用 MDX 文件了。创建一个 .mdx 文件：

// example.mdx

# Hello, MDX!

Here's a neat component for you:

<MyComponent />

然后在一个 React 组件中导入它：

// App.js
import React from 'react';
import { MDXProvider } from '@mdx-js/react';
import Example from './example.mdx';

const components = {
  // 你可以在这里映射 MDX 标签到你的 React 组件
  h1: props => <h1 style={{ color: 'tomato' }} {...props} />,
  MyComponent: /* 你的自定义组件 */,
  // ... 其他组件映射
};

function App() {
  return (
    <MDXProvider components={components}>
      <div className="App">
        <Example />
      </div>
    </MDXProvider>
  );
}

export default App;

这将会渲染 example.mdx 文件，并且任何 MDX 文件中的标签都会被映射到你定义的 React 组件上。

请注意，实际设置 MDX 可能会根据您的特定项目配置和所使用的工具（如 Next.js、Gatsby 或其他）而有所不同。建议查看 MDX 官方文档，了解有关您所使用的环境的特定安装和配置指南。

5. 生态系统

MDX 的生态系统是由一系列工具、库、插件和社区支持构成的。由于 MDX 结合了 Markdown 和 React 的优点，并且适应了现代开发的流行趋势，因此它在前端开发者和内容创作者中获得了不错的接受度。以下是一些 MDX 生态系统的关键组成部分：

1. 核心库：

   • @mdx-js/mdx：MDX 转换器的核心库，可以将 MDX 转换为 JSX。
   • @mdx-js/react：用于在 React 应用程序中集成 MDX。

2. 插件和工具：

   • Webpack Loader：允许你使用 webpack 打包 MDX 文件。
   • Babel Plugin：用于在 Babel 中处理 MDX 文件。
   • ESLint 插件：帮助开发者检查和修正 MDX 文件中的代码质量。
   • Prettier 插件：用于格式化 MDX 文件。

3. 集成：

   • Next.js：Next.js 提供了对 MDX 的官方支持，使得在 Next.js 项目中使用 MDX 变得非常简单。
   • Gatsby：Gatsby 插件系统中有对 MDX 的支持，允许你在 Gatsby 站点中使用 MDX。
   • Create React App (CRA)：虽然 CRA 没有内置对 MDX 的支持，但可以通过自定义配置来集成 MDX。

4. 社区和资源：

   • 官方文档：MDX 官方网站提供了详细的文档和教程，帮助开发者上手和深入了解 MDX。
   • GitHub 存储库：MDX 的开发主要在 GitHub 上进行，社区成员可以贡献代码，提交问题和改进建议。
   • 在线编辑器和沙箱：如 CodeSandbox，支持 MDX，允许在线编辑和预览 MDX 文件。

5. UI 组件库：

   • 许多 UI 组件库和设计系统已经开始支持 MDX，方便开发者在 MDX 文件中直接使用这些组件。

6. 内容管理系统 (CMS)：

   • 一些支持头部管理 (headless CMS) 的内容管理系统也已经开始支持 MDX，使得非技术用户可以更轻松地管理和发布 MDX 内容。

MDX 的生态系统不断成长和改进，随着更多的开发者和公司采用 MDX，可以预见将会有更多的工具和集成选项出现。这个生态系统的发展有望进一步提高 MDX 的可用性和灵活性，使其成为创建交互式文档和应用程序的一个强大选择。

6. mdx vs marked

MDX 和 Marked 是两个不同的库，它们各自有不同的用途和特点。是否可以替代彼此通常取决于您的需求和使用情况。

Marked 是一个快速、轻量级的 Markdown 解析器和编译器，它的主要用途是将 Markdown 转换为 HTML。它是纯粹的 Markdown 转换器，不涉及任何 React 或组件的概念。如果您的需求仅仅是在网站上展示静态的 Markdown 内容，Marked 是一个很好的选择。

MDX，正如之前所述，是一种扩展了 Markdown 语法的格式，它允许在 Markdown 中直接使用 JSX 和 React 组件。MDX 更适合需要在 Markdown 中嵌入动态组件或交互功能的场景。

如果我们考虑替代性，这两种库可以在不同的场景下互相替代：

• 如果您需要的只是简单的 Markdown 到 HTML 转换，并不需要嵌入 React 组件或创建交互式内容，那么 Marked 可以很好地完成工作，而 MDX 可能会显得过于复杂。
• 如果您希望在 Markdown 内容中加入互动性，或者构建一个结合了静态内容和动态组件的复杂应用，MDX 将是更合适的选择。MDX 提供了 Marked 所没有的功能，如直接在 Markdown 文件中使用 React 组件。

总的来说，MDX 并不是直接替代 Marked 的库，而是为特定需要提供了更丰富的功能。选择使用哪个库应基于您的具体需求，以及您是否需要 React 和 JSX 在 Markdown 中的集成能力。如果您的项目已经在使用 React，并且您希望能够将 Markdown 和 React 组件更紧密地结合起来，MDX 是一个很好的选择。如果您只需要简单的 Markdown 解析功能，Marked 会是一个更轻量级和简单的选择。

7. 插件集成

集成插件到 MDX 中是一个相对直接的过程，但它可能会有所不同，取决于你使用的构建系统（例如，Webpack、Parcel 等）和你希望集成的插件类型。以下是一些通用步骤，展示了如何集成插件到一个使用 MDX 的项目中：

1. 安装插件

   先确定你想要使用的 MDX 插件，并使用 npm 或 yarn 安装它。以 remark-images 插件为例，这是一个用于自动将 Markdown 图片转换为响应式图片的插件。

   npm install remark-images

   或者使用 yarn：

   yarn add remark-images

2. 配置 MDX

   在你的构建配置中，你将需要指定 MDX 如何通过 remark（用于 Markdown 转换）和 rehype（用于 HTML 转换）插件来处理文件。对于 Webpack，你可能需要更新 MDX 的加载器配置：

   // webpack.config.js
   module.exports = {
     // ...
     module: {
       rules: [
         {
           test: /\.mdx?$/,
           use: [
             "babel-loader",
             {
               loader: "@mdx-js/loader",
               options: {
                 // 将插件传递给 MDX
                 remarkPlugins: [require("remark-images")],
                 // rehypePlugins: [require('some-rehype-plugin')],
               },
             },
           ],
         },
         // 其他 loaders...
       ],
     },
     // ...
   };

3. 在 React 组件中使用 MDX

   现在你可以在你的 React 组件中正常使用 MDX 文件了，并且任何你已经配置的插件都会被应用到这些文件中。

4. 自定义插件

   如果你需要进一步自定义插件的行为，你可以查阅插件的文档以了解可用的配置选项。在上面的配置中，你可以传递配置对象给插件，而不仅仅是插件本身：

   {
     loader: '@mdx-js/loader',
     options: {
       remarkPlugins: [
         [require('remark-images'), {/* 插件的配置选项 */}]
       ],
       // rehypePlugins: [...],
     },
   }

5. 处理依赖

   有些插件可能依赖其他包。确保你阅读了插件的安装说明，并且安装了所有必要的依赖。

6. 测试

   最后，确保你测试了新集成的插件。运行你的构建过程，检查插件是否按照预期工作，并且没有产生任何不期望的副作用。

请注意，上述步骤基于 Webpack 的示例。如果你使用的是其他工具链（如 Parcel、Rollup 或其他静态站点生成器），你需要参照这些工具的文档来调整集成过程。

此外，MDX 社区提供了许多有用的插件，所以当你遇到特定的需求时，最好查看现有的选项是否已经有人解决了类似的问题。如果没有，你也可以考虑编写自己的插件来扩展 MDX 的功能。

---

微信搜索"好朋友乐平"关注公众号。

github原文地址