Menu

Markdown and MDX

Markdown 是一种用于格式化文本的轻量级标记语言。它允许你使用纯文本语法编写，并将其转换为结构有效的 HTML。它常用于编写网站和博客的内容。

你可以这样写...

我 **喜欢** 使用 [Next.js](https://nextjs.org/)

输出结果：

<p>我 <strong>喜欢</strong> 使用 <a href="https://nextjs.org/">Next.js</a></p>

MDX 是 markdown 的超集，它允许你直接在 markdown 文件中编写 JSX。这是一种强大的方式，可以添加动态交互性并在你的内容中嵌入 React 组件。

Next.js 可以支持应用程序内的本地 MDX 内容，以及在服务器上动态获取的远程 MDX 文件。Next.js 插件负责将 markdown 和 React 组件转换为 HTML，包括支持在服务器组件中使用 (在 App Router 中默认使用)。

值得注意: 查看 Portfolio Starter Kit 模板以获取完整的工作示例。

安装依赖

@next/mdx 包及相关包用于配置 Next.js，以便处理 markdown 和 MDX。它从本地文件获取数据，允许你直接在 /pages 或 /app 目录中创建带有 .md 或 .mdx 扩展名的页面。

安装这些包以在 Next.js 中渲染 MDX：

Terminal
npm install @next/mdx @mdx-js/loader @mdx-js/react @types/mdx

配置 next.config.mjs

更新项目根目录下的 next.config.mjs 文件，以配置它使用 MDX：

next.config.mjs
import createMDX from "@next/mdx";
 
/** @type {import('next').NextConfig} */
const nextConfig = {
  // 配置 `pageExtensions` 以包含 markdown 和 MDX 文件
  pageExtensions: ["js", "jsx", "md", "mdx", "ts", "tsx"],
  // 可选地，在此处添加任何其他 Next.js 配置
};
 
const withMDX = createMDX({
  // 在这里添加 markdown 插件，根据需要
});
 
// 将 MDX 配置与 Next.js 配置合并
export default withMDX(nextConfig);

这允许 .md 和 .mdx 文件在你的应用程序中充当页面、路由或导入。

添加 mdx-components.tsx 文件

在项目根目录创建一个 mdx-components.tsx (或 .js) 文件，以定义全局 MDX 组件。例如，与 pages 或 app 在同一级别，或者如果适用的话，在 src 内部。

mdx-components.tsx
TypeScript
import type { MDXComponents } from "mdx/types";
 
export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    ...components,
  };
}
mdx-components.js
export function useMDXComponents(components) {
  return {
    ...components,
  };
}

值得注意:

渲染 MDX

你可以使用 Next.js 的基于文件的路由或通过将 MDX 文件导入到其他页面来渲染 MDX。

使用基于文件的路由

当使用基于文件的路由时，你可以像使用任何其他页面一样使用 MDX 页面。

在 /pages 目录中创建一个新的 MDX 页面：

  my-project
  |── mdx-components.(tsx/js)
  ├── pages
  │   └── mdx-page.(mdx/md)
  └── package.json

你可以在这些文件中使用 MDX，甚至可以直接在 MDX 页面中导入 React 组件：

import { MyComponent } from "my-component";
 
# 欢迎来到我的 MDX 页面！
 
这是一些**粗体**和*斜体*文本。
 
这是 markdown 中的列表：
 
- 一
- 二
- 三
 
查看我的 React 组件：
 
<MyComponent />

导航到 /mdx-page 路由应该显示你渲染的 MDX 页面。

使用导入

在 /pages 目录中创建一个新页面，并在你想要的任何位置创建一个 MDX 文件：

  my-project
  ├── pages
  │   └── mdx-page.(tsx/js)
  ├── markdown
  │   └── welcome.(mdx/md)
  |── mdx-components.(tsx/js)
  └── package.json

你可以在这些文件中使用 MDX，甚至可以直接在 MDX 页面中导入 React 组件：

markdown/welcome.mdx
import { MyComponent } from "my-component";
 
# 欢迎来到我的 MDX 页面！
 
这是一些**粗体**和*斜体*文本。
 
这是 markdown 中的列表：
 
- 一
- 二
- 三
 
查看我的 React 组件：
 
<MyComponent />

在页面中导入 MDX 文件以显示内容：

pages/mdx-page.tsx
TypeScript
import Welcome from "@/markdown/welcome.mdx";
 
export default function Page() {
  return <Welcome />;
}

导航到 /mdx-page 路由应该显示你渲染的 MDX 页面。

使用自定义样式和组件

Markdown 在渲染时会映射到原生 HTML 元素。例如，编写以下 markdown：

## 这是一个标题
 
这是 markdown 中的列表：
 
- 一
- 二
- 三

生成以下 HTML：

<h2>这是一个标题</h2>
 
<p>这是 markdown 中的列表：</p>
 
<ul>
  <li>一</li>
  <li>二</li>
  <li>三</li>
</ul>

要为你的 markdown 添加样式，你可以提供映射到生成的 HTML 元素的自定义组件。样式和组件可以全局实现、局部实现，并使用共享布局。

全局样式和组件

在 mdx-components.tsx 中添加样式和组件将影响应用程序中的所有 MDX 文件。

mdx-components.tsx
TypeScript
import type { MDXComponents } from "mdx/types";
import Image, { ImageProps } from "next/image";
 
// 这个文件允许你提供自定义 React 组件
// 以在 MDX 文件中使用。你可以导入和使用任何
// 你想要的 React 组件，包括内联样式、
// 其他库的组件等等。
 
export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    // 允许自定义内置组件，例如添加样式。
    h1: ({ children }) => (
      <h1 style={{ color: "red", fontSize: "48px" }}>{children}</h1>
    ),
    img: (props) => (
      <Image
        sizes="100vw"
        style={{ width: "100%", height: "auto" }}
        {...(props as ImageProps)}
      />
    ),
    ...components,
  };
}
mdx-components.js
import Image from "next/image";
 
// 这个文件允许你提供自定义 React 组件
// 以在 MDX 文件中使用。你可以导入和使用任何
// 你想要的 React 组件，包括内联样式、
// 其他库的组件等等。
 
export function useMDXComponents(components) {
  return {
    // 允许自定义内置组件，例如添加样式。
    h1: ({ children }) => (
      <h1 style={{ color: "red", fontSize: "48px" }}>{children}</h1>
    ),
    img: (props) => (
      <Image
        sizes="100vw"
        style={{ width: "100%", height: "auto" }}
        {...props}
      />
    ),
    ...components,
  };
}

局部样式和组件

你可以通过将局部样式和组件传递给导入的 MDX 组件来应用它们到特定页面。这些将与全局样式和组件合并并覆盖它们。

pages/mdx-page.tsx
TypeScript
import Welcome from "@/markdown/welcome.mdx";
 
function CustomH1({ children }) {
  return <h1 style={{ color: "blue", fontSize: "100px" }}>{children}</h1>;
}
 
const overrideComponents = {
  h1: CustomH1,
};
 
export default function Page() {
  return <Welcome components={overrideComponents} />;
}

共享布局

要在 MDX 页面周围共享布局，创建一个布局组件：

components/mdx-layout.tsx
TypeScript
export default function MdxLayout({ children }: { children: React.ReactNode }) {
  // 在这里创建任何共享布局或样式
  return <div style={{ color: "blue" }}>{children}</div>;
}

然后，将布局组件导入到 MDX 页面中，用布局包裹 MDX 内容，并导出它：

import MdxLayout from "../components/mdx-layout";
 
# 欢迎来到我的 MDX 页面！
 
export default function MDXPage({ children }) {
  return <MdxLayout>{children}</MdxLayout>
 
}

使用 Tailwind 排版插件

如果你正在使用 Tailwind 来为你的应用程序添加样式，使用 @tailwindcss/typography 插件将允许你在 markdown 文件中重用你的 Tailwind 配置和样式。

该插件添加了一组 prose 类，可用于为来自源（如 markdown）的内容块添加排版样式。

安装 Tailwind 排版并与共享布局一起使用以添加你想要的 prose。

要在 MDX 页面周围共享布局，创建一个布局组件：

components/mdx-layout.tsx
TypeScript
export default function MdxLayout({ children }: { children: React.ReactNode }) {
  // 在这里创建任何共享布局或样式
  return (
    <div className="prose prose-headings:mt-8 prose-headings:font-semibold prose-headings:text-black prose-h1:text-5xl prose-h2:text-4xl prose-h3:text-3xl prose-h4:text-2xl prose-h5:text-xl prose-h6:text-lg dark:prose-headings:text-white">
      {children}
    </div>
  );
}

然后，将布局组件导入到 MDX 页面中，用布局包裹 MDX 内容，并导出它：

import MdxLayout from "../components/mdx-layout";
 
# 欢迎来到我的 MDX 页面！
 
export default function MDXPage({ children }) {
  return <MdxLayout>{children}</MdxLayout>
 
}

前置元数据

前置元数据是一种类似 YAML 的键值对，可用于存储页面相关的数据。@next/mdx 默认不支持前置元数据，但有许多解决方案可以为你的 MDX 内容添加前置元数据，例如：

@next/mdx 确实允许你像任何其他 JavaScript 组件一样使用导出：

content/blog-post.mdx
export const metadata = {
  author: "张三",
};
 
# 博客文章

现在可以在 MDX 文件外部引用元数据：

pages/blog.tsx
TypeScript
import BlogPost, { metadata } from '@/content/blog-post.mdx'
 
export default function Page() {
  console.log('metadata': metadata)
  //=> { author: '张三' }
  return <BlogPost />
}

这种方法的一个常见用例是当你想要遍历 MDX 集合并提取数据时。例如，从所有博客文章创建博客索引页面。你可以使用像 Node 的 fs 模块或 globby 这样的包来读取帖子目录并提取元数据。

值得注意:

  • 使用 fs、globby 等只能在服务器端使用。
  • 查看 Portfolio Starter Kit 模板以获取完整的工作示例。

Remark 和 Rehype 插件

你可以选择提供 remark 和 rehype 插件来转换 MDX 内容。

例如，你可以使用 remark-gfm 来支持 GitHub Flavored Markdown。

由于 remark 和 rehype 生态系统仅支持 ESM，你需要使用 next.config.mjs 作为配置文件。

next.config.mjs
import remarkGfm from "remark-gfm";
import createMDX from "@next/mdx";
 
/** @type {import('next').NextConfig} */
const nextConfig = {
  // 配置 `pageExtensions` 以包含 MDX 文件
  pageExtensions: ["js", "jsx", "md", "mdx", "ts", "tsx"],
  // 可选地，在此处添加任何其他 Next.js 配置
};
 
const withMDX = createMDX({
  // 在这里添加 markdown 插件，根据需要
  options: {
    remarkPlugins: [remarkGfm],
    rehypePlugins: [],
  },
});
 
// 将 MDX 配置和 Next.js 配置互相包裹
export default withMDX(nextConfig);

远程 MDX

如果你的 MDX 文件或内容存在于其他地方，你可以在服务器上动态获取它。这对于存储在单独的本地文件夹、CMS、数据库或任何其他地方的内容很有用。一个流行的社区包用于此目的是 next-mdx-remote。

值得注意: 请谨慎处理。MDX 编译成 JavaScript 并在服务器上执行。你应该只从受信任的源获取 MDX 内容，否则可能导致远程代码执行 (RCE)。

以下示例使用 next-mdx-remote：

pages/mdx-page-remote.tsx
TypeScript
import { serialize } from "next-mdx-remote/serialize";
import { MDXRemote, MDXRemoteSerializeResult } from "next-mdx-remote";
 
interface Props {
  mdxSource: MDXRemoteSerializeResult;
}
 
export default function RemoteMdxPage({ mdxSource }: Props) {
  return <MDXRemote {...mdxSource} />;
}
 
export async function getStaticProps() {
  // MDX 文本 - 可以来自本地文件、数据库、CMS、fetch、任何地方...
  const res = await fetch("https:...");
  const mdxText = await res.text();
  const mdxSource = await serialize(mdxText);
  return { props: { mdxSource } };
}

导航到 /mdx-page-remote 路由应该显示你渲染的 MDX。

深入探讨：如何将 markdown 转换为 HTML？

React 原生不理解 markdown。markdown 纯文本首先需要转换为 HTML。这可以通过 remark 和 rehype 来完成。

remark 是围绕 markdown 的工具生态系统。rehype 是同样的，但针对 HTML。例如，以下代码片段将 markdown 转换为 HTML：

import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import rehypeSanitize from "rehype-sanitize";
import rehypeStringify from "rehype-stringify";
 
main();
 
async function main() {
  const file = await unified()
    .use(remarkParse) // 转换为 markdown AST
    .use(remarkRehype) // 转换为 HTML AST
    .use(rehypeSanitize) // 净化 HTML 输入
    .use(rehypeStringify) // 将 AST 转换为序列化的 HTML
    .process("你好，Next.js！");
 
  console.log(String(file)); // <p>你好，Next.js！</p>
}

remark 和 rehype 生态系统包含用于语法高亮、链接标题、生成目录等的插件。

当使用上面所示的 @next/mdx 时，你不需要直接使用 remark 或 rehype，因为它已经为你处理了。我们在这里描述它是为了更深入地理解 @next/mdx 包在底层做了什么。

使用基于 Rust 的 MDX 编译器（实验性）

Next.js 支持一个用 Rust 编写的新 MDX 编译器。这个编译器仍处于实验阶段，不建议在生产环境中使用。要使用新编译器，你需要在将其传递给 withMDX 时配置 next.config.js：

next.config.js
module.exports = withMDX({
  experimental: {
    mdxRs: true,
  },
});

mdxRs 还接受一个对象来配置如何转换 mdx 文件。

next.config.js
module.exports = withMDX({
  experimental: {
    mdxRs: {
      jsxRuntime?: string            // 自定义 jsx运行时
      jsxImportSource?: string       // 自定义 jsx 导入源
      mdxType?: 'gfm' | 'commonmark' // 配置将用于解析和转换的 mdx 语法类型
    },
  },
})

值得注意:

当使用 Turbopack (next dev --turbo) 处理 markdown 和 MDX 时，需要此选项。

有用的链接