Gatsby - 从 Markdown 切换到 MDX

由 Mux 主办的 DEV 全球展示挑战赛：展示你的项目！

最近，我把之前托管在 GoDaddy 上的 WordPress 网站重写成了托管在Netlify上的Gatsby网站。一开始我尝试自己手动搭建网站，但要实现所有想要的功能实在太耗时了。幸好 Gatsby 的入门模板帮了我大忙！我选择的模板包含了所有我需要的功能：标签、搜索、博客和联系表单。剩下的几个功能，比如社交链接、项目页面和关于我们页面，我可以以后慢慢添加。

该模板采用的是 Gatsby 默认的纯 Markdown 文件格式。为了增强文章和组件的功能，我需要切换到MDX。

做出改变🎉

在 Gatsby 中使用 MDX 需要几个不同的软件包。首先，请安装它们。

npm install --save @mdx-js/mdx @mdx-js/react gatsby-plugin-feed-mdx gatsby-plugin-mdx

Gatsby-Plugin-MDX

在gatsby-config.js重命名导出部分时，将 `<exports>` 替换为 ` gatsby-transofrmer-remark<import>` gatsby-plugin-mdx。这将告诉 Gatsby 使用 MDX 插件，并停止对纯 Markdown 文件使用转换器。将plugins节点重命名为 ` gatsbyRemarkPlugins<import>`，并保留之前的插件（有一两个例外，我们稍后会介绍）。我希望该插件能够同时支持 MDX 和 Markdown，并使用我已有的模板。

        extensions: [`.mdx`, `.md`],
        defaultLayouts: {
          posts: require.resolve('./src/templates/PostTemplate.js'),
          page: require.resolve('./src/templates/PageTemplate.js'),
          tags: require.resolve('./src/templates/TagTemplate.js'),
        },

Gatbsy-Plugin-Feed-MDX

如果您已设置发布 RSS 源，则需要切换到此软件包，这是gatsby-config.js我们需要重命名的另一个插件。请将您的源查询从allMarkdownRemark调整为allMdx。

- serialize: ({ query: { site, allMarkdownRemark } }) => {
- return allMarkdownRemark.edges.map(edge => {
+ serialize: ({ query: { site, allMdx } }) => {
+ return allMdx.edges.map(edge => {

更改所有查询

我们需要对网站内的所有查询进行上述更改。如果您有一个查询只是markdownRemarkMDX 版本，那么只需进行上述更改即可mdx。这可能有点繁琐，但别担心，并没有那么糟糕。

- posts: allMarkdownRemark(
+ posts: allMdx(

- page: markdownRemark(fields: { slug: { eq: $slug } }) {
+ page: mdx(fields: { slug: { eq: $slug } }) {
       id
-      html
+      body

更改组件和属性

现在所有查询都已更新，我们需要将更新后的查询结果传递给组件，并确保它们在 props 中正确更新。以下示例展示了这种更改的效果，该示例来自BodyText我使用的模板自带的一个组件。

我们需要使用这个组件，而不是dangerouslySetInnerHTMLMDX。我的需求是，只需将bodyGraphQL 查询返回的结果封装在这个组件中，它就能渲染出 MDX 内容。

import { MDXRenderer } from 'gatsby-plugin-mdx'

更改组件的 props 以body代替html

- const { html, theme } = props
+ const { body, theme } = props

使用该MDXRenderer组件将结果渲染到页面上。

- <div className="bodytext" dangerouslySetInnerHTML={{ __html: html }} />
+ <div className="bodytext">
+   <MDXRenderer>{body}</MDXRenderer>
+ </div>

将组件的 propTypes 从 更改html为body。

- html: PropTypes.string.isRequired,
+ body: PropTypes.string.isRequired,

根据组件的不同，只需应用这些及类似的更改，我就能够在短时间内更新所有组件。

旧软件包

完成所有这些更改后，您的 Gatsby 页面应该就可以使用 MDX 正常运行了。您可以根据需要将所有旧的 MDX 代码迁移到 MDX，否则，请保持扩展选项不变，它们应该可以正确渲染。现在是时候移除不再使用的包了。

npm uninstall gatsby-plugin-feed gatsby-transformer-remark

陷阱

过程中遇到了一些小问题，让我有点措手不及，这些问题可能与我的设置方式有关，但我还是想在这里提一下。

MDX 无法渲染代码块语法高亮

在切换到 MDX 之前，我并不知道它默认不支持代码块渲染。不过，有很多方法可以解决这个问题，我选择了添加 PrismJS，并使用他们提供的 CSS 文件来美化代码块的外观。如果你对此感兴趣，我强烈推荐你了解一下这个gatsby-remark-prismjs 插件。

Jest快照测试停止运行

我之前有一个 Jest Snapshot 测试，用于测试文章组件，该组件包含头部、主体以及相应的样式。切换组件后，测试的主体部分开始失败，我需要在 Jest 配置中添加一个排除项来忽略它gatsby-plugin-mdx。它预加载了一些 Jest 未预期的内容。

- transformIgnorePatterns: [`node_modules/(?!(gatsby)/)`],
+ transformIgnorePatterns: ['node_modules/(?!(gatsby|gatsby-plugin-mdx)/)'],

如果你已经从 Gatsby 切换到 MDX，我很想知道你的使用体验如何。你是否遇到过和我一样的问题，或者你是否使用了其他包/解决方案来处理代码块渲染？