Mdx 讓 Markdown 步入組件時代
前言
在 MDX 出現之前，將 JSX 與 Markdown 混合書寫時，Markdown 的優勢就不存在了。通常是基于模板字符串的方式，因此就需要大量的轉義和繁瑣的語法。
MDX 試圖讓書寫 Markdown 和 JSX 更簡單、更具 表現力。當你將組件 (甚至可以是動態的或需要加載數據的組件)與 Markdown 混合書寫時，你將寫出更有趣的內容。
MDX 是什么
MDX 是一種書寫格式，允許你在 Markdown 文檔中無縫地插入 JSX 代碼。你還可以導入(import)組件，例如交互式圖表或彈框，并將它們 嵌入到內容當中。
前提條件
您應該熟悉 markdown 語法和 JavaScript 語法 (特別是 JSX)。
MDX 示例比如官網的一個例子，如下代碼
import {Chart} from './snowfall.js'
export const year = 2018
# 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" />
展示效果
效果.png
如何使用
在 create-react-app 中 只需要安裝 @mdx-js/loader， create-react-app 5 支持自定義 loader
src/App.jsx
/* eslint-disable import/no-webpack-loader-syntax */
import Content from "!@mdx-js/loader!./content.mdx";
export default function App() {
return <Content />;
}
src/content.mdx
# Hello, world!
This is **markdown** with <span style={{color: "red"}}>JSX</span>: MDX!
如果是 webpack 項目只需要加一個 @mdx-js/loader就可以支持
module.exports = {
module: {
// …
rules: [
// …
{
test: /\.mdx?$/,
use: [
// `babel-loader` is optional:
{ loader: "babel-loader", options: {} },
{
loader: "@mdx-js/loader",
/** @type {import('@mdx-js/loader').Options} */
options: {
/* jsxImportSource: …, otherOptions… */
},
},
],
},
],
},
};
插件支持
MDX 也支持插件配置，也就是原先的 markdown 插件
比如要讓 markdown 支持表格和 checkboxList ，可以使用 remark-gfm 插件;
比如要讓 markdown 支持數學公式 可以使用 rehype-katex 插件;
在 option 中可以傳入參數，代碼如下：
import rehypeKatex from 'rehype-katex'
import remarkMath from 'remark-math'
module.exports = {
module: {
// …
rules: [
// …
{
test: /\.mdx?$/,
use: [
// `babel-loader` is optional:
{loader: 'babel-loader', options: {}},
{
loader: '@mdx-js/loader',
/** @type {import('@mdx-js/loader').Options} */
options: {remarkPlugins: [remarkGfm], rehypePlugins: [rehypeKatex]}}
}
]
}
]
}
}
當然也可以支持自定義插件，比如 img 要加上默認樣式，限制其最大寬度，href 跳轉要改成新窗口打開等 ，如何寫 markdown 插件可以查看 unifiedjs.com
定義組件
在支持了 mdx 之后， 可以給 mdx 定義組件, 比如給 H1 傳遞默認樣式等，或者加入默認組件，例如 https://beta.reactjs.org/ 就加入了很多自定義組件，代碼示例如下：
import React from "react";
import ReactDom from "react-dom";
import Post from "./post.mdx"; // Assumes an integration is used
export const H1 = ({ className, ...props }: HeadingProps) => (
<H1
className={cn(className, "text-5xl font-bold leading-tight")}
{...props}
/>
);
const components = {
h1: H1,
};
ReactDom.render(
<Post components={components} />,
document.querySelector("#root")
);
MDX provider
每個文檔都要傳 components 很麻煩?我們可以在最外層導入 MDXProvider
import React from 'react'
import ReactDom from 'react-dom'
import Post from './post.mdx' // Assumes an integration is used to compile MDX -> JS.
import {Heading, /* … */ Table} from './components/index.js'
+import {MDXProvider} from '@mdx-js/react'
const components = {
h1: Heading.H1,
// …
table: Table
}
ReactDom.render(
- <Post components={components} />,
+ <MDXProvider components={components}>
+ <Post />
+ </MDXProvider>,
document.querySelector('#root')
)
在線運行
以上實例都是在構建時運行，那么能讓 MDX 在瀏覽器運行呢，比如未來，博客的編輯器支持 MDX， 那么我們的博客文章頁面就可以有更多交互了。
比如數據通過服務端返回,下面代碼是 next.js 示例
import { useState, useEffect, Fragment } from "react";
import * as runtime from "react/jsx-runtime.js";
import { compile, run } from "@mdx-js/mdx";
export default function Page({ code }) {
const [mdxModule, setMdxModule] = useState();
const Content = mdxModule ? mdxModule.default : Fragment;
useEffect(() => {
(async () => {
setMdxModule(await run(code, runtime));
})();
}, [code]);
return <Content />;
}
export async function getStaticProps() {
const code = String(
await compile("# hi", { outputFormat: "function-body" /* …otherOptions */ })
);
return { props: { code } };
}
實時運行
例如：官方的 palyground，就可以實時運行，左邊寫代碼，右側展示文檔
官方 playground
最簡單的代碼如下：
import { VFile } from "vfile";
import { evaluate, } from "@mdx-js/mdx";
const value='## header'
const file = new VFile({ basename: "example.mdx", value });
const {default:Result}=await evaluate(file, runtime);
這個 Result 就是一個react 組件，如要實現類似功能可以參考官方 github 中的 editor.client.js。
小結
Markdown 所有程序員都愛，Markdown 在標準化、結構化、組件化都存在硬傷，有了 MDX ，Markdown 有了富交互、內容形態的編寫，希望 MDX 盡早、盡快、更多的投入到的互聯網產品中，也希望 MDX 的解析也來越標準化。
