如何在 Next.js 中使用 markdown 和 MDX

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

您编写...

I **love** using [Next.js](https://nextjs.net.cn/)

输出

<p>I <strong>love</strong> using <a href="https://nextjs.net.cn/">Next.js</a></p>

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

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

需要知道：请参阅个人作品集入门套件模板以获取完整的示例。

安装依赖

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

安装这些包以使用 Next.js 渲染 MDX

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

配置 `next.config.mjs`

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

import createMDX from '@next/mdx'
 
/** @type {import('next').NextConfig} */
const nextConfig = {
  // Configure `pageExtensions` to include markdown and MDX files
  pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
  // Optionally, add any other Next.js config below
}
 
const withMDX = createMDX({
  // Add markdown plugins here, as desired
})
 
// Merge MDX config with Next.js config
export default withMDX(nextConfig)

这允许 .mdx 文件在您的应用程序中作为页面、路由或导入使用。

处理 `.md` 文件

默认情况下，next/mdx 仅编译 .mdx 扩展名的文件。要使用 webpack 处理 .md 文件，请更新 extension 选项

const withMDX = createMDX({
  extension: /\.(md|mdx)$/,
})

添加 `mdx-components.tsx` 文件

在项目的根目录（例如，与 pages 或 app 处于同一级别，或在 src 内部，如果适用）中创建一个 mdx-components.tsx（或 .js）文件来定义全局 MDX 组件。

import type { MDXComponents } from 'mdx/types'
 
const components: MDXComponents = {}
 
export function useMDXComponents(): MDXComponents {
  return components
}

须知:

使用 App Router 时，mdx-components.tsx 是使用 @next/mdx 必需的，没有它将无法工作。

了解更多关于 mdx-components.tsx 文件约定。

了解如何使用自定义样式和组件。

渲染 MDX

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

使用基于文件的路由

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

在 App Router 应用程序中，这包括能够使用元数据。

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

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

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

import { MyComponent } from 'my-component'
 
# Welcome to my MDX page!
 
This is some **bold** and _italics_ text.
 
This is a list in markdown:
 
- One
- Two
- Three
 
Checkout my React component:
 
<MyComponent />

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

使用导入

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

  .
  ├── app/
  │   └── mdx-page/
  │       └── page.(tsx/js)
  ├── markdown/
  │   └── welcome.(mdx/md)
  ├── mdx-components.(tsx/js)
  └── package.json

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

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

import Welcome from '@/markdown/welcome.mdx'
 
export default function Page() {
  return <Welcome />
}

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

使用动态导入

您可以导入动态 MDX 组件，而不是使用 MDX 文件的文件系统路由。

例如，您可以有一个动态路由段，它从单独的目录加载 MDX 组件

Route segments for dynamic MDX components

generateStaticParams 可用于预渲染提供的路由。通过将 dynamicParams 标记为 false，访问未在 generateStaticParams 中定义的路由将返回 404。

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const { default: Post } = await import(`@/content/${slug}.mdx`)
 
  return <Post />
}
 
export function generateStaticParams() {
  return [{ slug: 'welcome' }, { slug: 'about' }]
}
 
export const dynamicParams = false

需要知道：请确保在导入中指定 .mdx 文件扩展名。虽然不强制使用模块路径别名（例如，@/content），但它确实简化了您的导入路径。

使用自定义样式和组件

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

## This is a heading
 
This is a list in markdown:
 
- One
- Two
- Three

生成以下 HTML

<h2>This is a heading</h2>
 
<p>This is a list in markdown:</p>
 
<ul>
  <li>One</li>
  <li>Two</li>
  <li>Three</li>
</ul>

要为 markdown 设置样式，您可以提供映射到生成的 HTML 元素的自定义组件。样式和组件可以在全局、局部和共享布局中实现。

全局样式和组件

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

import type { MDXComponents } from 'mdx/types'
import Image, { ImageProps } from 'next/image'
 
// This file allows you to provide custom React components
// to be used in MDX files. You can import and use any
// React component you want, including inline styles,
// components from other libraries, and more.
 
const components = {
  // Allows customizing built-in components, e.g. to add styling.
  h1: ({ children }) => (
    <h1 style={{ color: 'red', fontSize: '48px' }}>{children}</h1>
  ),
  img: (props) => (
    <Image
      sizes="100vw"
      style={{ width: '100%', height: 'auto' }}
      {...(props as ImageProps)}
    />
  ),
} satisfies MDXComponents
 
export function useMDXComponents(): MDXComponents {
  return components
}

局部样式和组件

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

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 页面之间共享布局，您可以使用 App Router 的内置布局支持。

export default function MdxLayout({ children }: { children: React.ReactNode }) {
  // Create any shared layout or styles here
  return <div style={{ color: 'blue' }}>{children}</div>
}

使用 Tailwind 排版插件

如果您使用 Tailwind 为应用程序设置样式，使用 @tailwindcss/typography 插件将允许您在 markdown 文件中重用 Tailwind 配置和样式。

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

安装 Tailwind 排版插件，并将其与共享布局一起使用以添加您想要的 prose。

export default function MdxLayout({ children }: { children: React.ReactNode }) {
  // Create any shared layout or styles here
  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>
  )
}

前言

Frontmatter 是一种 YAML 键/值对，可用于存储页面的数据。@next/mdx 默认不支持 frontmatter，但有许多解决方案可以为您的 MDX 内容添加 frontmatter，例如

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

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

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

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

须知:

使用 fs、globby 等只能在服务器端使用。

请参阅个人作品集入门套件模板以获取完整的示例。

remark 和 rehype 插件

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

例如，您可以使用 remark-gfm 来支持 GitHub 风格的 Markdown。

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

import remarkGfm from 'remark-gfm'
import createMDX from '@next/mdx'
 
/** @type {import('next').NextConfig} */
const nextConfig = {
  // Allow .mdx extensions for files
  pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
  // Optionally, add any other Next.js config below
}
 
const withMDX = createMDX({
  // Add markdown plugins here, as desired
  options: {
    remarkPlugins: [remarkGfm],
    rehypePlugins: [],
  },
})
 
// Combine MDX and Next.js config
export default withMDX(nextConfig)

在 Turbopack 中使用插件

要将插件与 Turbopack 一起使用，请升级到最新的 @next/mdx 并使用字符串指定插件名称

import createMDX from '@next/mdx'
 
/** @type {import('next').NextConfig} */
const nextConfig = {
  pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
}
 
const withMDX = createMDX({
  options: {
    remarkPlugins: [
      // Without options
      'remark-gfm',
      // With options
      ['remark-toc', { heading: 'The Table' }],
    ],
    rehypePlugins: [
      // Without options
      'rehype-slug',
      // With options
      ['rehype-katex', { strict: true, throwOnError: true }],
    ],
  },
})
 
export default withMDX(nextConfig)

须知:

暂不能使用不带可序列化选项的 remark 和 rehype 插件，因为 JavaScript 函数无法传递给 Rust。

远程 MDX

如果您的 MDX 文件或内容位于其他位置，您可以在服务器上动态获取它。这对于存储在 CMS、数据库或任何其他位置的内容非常有用。此用途的一个社区包是 next-mdx-remote-client。

注意：请谨慎操作。MDX 会编译成 JavaScript 并在服务器上执行。您应该只从受信任的源获取 MDX 内容，否则这可能导致远程代码执行 (RCE)。

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

import { MDXRemote } from 'next-mdx-remote-client/rsc'
 
export default async function RemoteMdxPage() {
  // MDX text - can be from a database, CMS, fetch, anywhere...
  const res = await fetch('https://...')
  const markdown = await res.text()
  return <MDXRemote source={markdown} />
}

导航到 /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) // Convert into markdown AST
    .use(remarkRehype) // Transform to HTML AST
    .use(rehypeSanitize) // Sanitize HTML input
    .use(rehypeStringify) // Convert AST into serialized HTML
    .process('Hello, Next.js!')
 
  console.log(String(file)) // <p>Hello, Next.js!</p>
}

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

如上所示，当使用 @next/mdx 时，您不需要直接使用 remark 或 rehype，因为它们会为您处理。我们在这里对其进行描述是为了让您更深入地了解 @next/mdx 包的底层工作原理。

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

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

module.exports = withMDX({
  experimental: {
    mdxRs: true,
  },
})

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

module.exports = withMDX({
  experimental: {
    mdxRs: {
      jsxRuntime?: string            // Custom jsx runtime
      jsxImportSource?: string       // Custom jsx import source,
      mdxType?: 'gfm' | 'commonmark' // Configure what kind of mdx syntax will be used to parse & transform
    },
  },
})