NNext.js 中文网 GitHub

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

了解如何配置 MDX 并在你的 Next.js 应用中使用它。

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

你编写……

md
我**喜欢**使用 [Next.js](https://s.nodejs.cn/467aae08-be28-4a45-a7a3-7b0b687391aa)

输出:

html
<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,包括对在 Server Component 中使用(App Router 中的默认方式)的支持。

小知识:查看 Portfolio Starter Kit 模板,获取完整的可运行示例。

安装依赖#

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

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

bash · pnpm
pnpm add @next/mdx @mdx-js/loader @mdx-js/react @types/mdx
bash · npm
npm install @next/mdx @mdx-js/loader @mdx-js/react @types/mdx
bash · yarn
yarn add @next/mdx @mdx-js/loader @mdx-js/react @types/mdx
bash · bun
bun add @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)

这使得 .mdx 文件可以在你的应用程序中充当页面、路由或导入项。

处理 .md 文件#

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

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

添加 mdx-components.tsx 文件#

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

mdx-components.tsx
import type { MDXComponents } from 'mdx/types'

const components: MDXComponents = {}

export function useMDXComponents(): MDXComponents {
  return components
}
mdx-components.js
const components = {}

export function useMDXComponents() {
  return components
}

小知识:

渲染 MDX#

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

使用基于文件的路由#

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

在 App Router 应用中,这包括能够使用 metadata。

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

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

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

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

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

mdx
import { MyComponent } from 'my-component'

# 欢迎来到我的 MDX 页面!

这是一些**粗体**和 _斜体_ 文本。

这是一个 markdown 列表:

- 一
- 二
- 三

来看看我的 React 组件:

<MyComponent />

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

使用导入#

在 /app 目录中创建一个新页面,并在任意位置创建一个 MDX 文件:

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

在 /pages 目录中创建一个新页面,并在任意位置创建一个 MDX 文件:

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

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

markdown/welcome.mdx
import { MyComponent } from 'my-component'

# 欢迎来到我的 MDX 页面!

这是一些**粗体**和 _斜体_ 文本。

这是一个 markdown 列表:

- 一
- 二
- 三

来看看我的 React 组件:

<MyComponent />

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

app/mdx-page/page.tsx
import Welcome from '@/markdown/welcome.mdx'

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

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

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

export default function Page() {
  return <Welcome />
}

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

使用动态导入#

你可以导入动态 MDX 组件,而不是为 MDX 文件使用文件系统路由。

例如,你可以设置一个动态路由段,从单独的目录加载 MDX 组件:

generateStaticParams 可用于预渲染提供的路由。在导入之前,请检查请求的 slug 是否映射到真实文件,如果文件不存在则调用 notFound():

app/blog/[slug]/page.tsx
import { notFound } from 'next/navigation'

const contentSlugs = ['welcome', 'about']

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params

  if (!contentSlugs.includes(slug)) {
    notFound()
  }

  const { default: Post } = await import(`@/content/${slug}.mdx`)

  return <Post />
}

export function generateStaticParams() {
  return contentSlugs.map((slug) => ({ slug }))
}
app/blog/[slug]/page.js
import { notFound } from 'next/navigation'

const contentSlugs = ['welcome', 'about']

export default async function Page({ params }) {
  const { slug } = await params

  if (!contentSlugs.includes(slug)) {
    notFound()
  }

  const { default: Post } = await import(`@/content/${slug}.mdx`)

  return <Post />
}

export function generateStaticParams() {
  return contentSlugs.map((slug) => ({ slug }))
}

小知识:确保在导入时指定 .mdx 文件扩展名。虽然使用模块路径别名(例如 @/content)并非必需,但它确实能简化你的导入路径。

使用自定义样式和组件#

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

md
## 这是一个标题

这是一个 markdown 列表:

- 一
- 二
- 三

生成以下 HTML:

html
<h2>这是一个标题</h2>

<p>这是一个 markdown 列表:</p>

<ul>
  <li>一</li>
  <li>二</li>
  <li>三</li>
</ul>

要为 markdown 设置样式,你可以提供映射到所生成 HTML 元素的自定义组件。样式和组件可以在全局、局部以及通过共享布局来实现。

全局样式和组件#

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

mdx-components.tsx
import type { MDXComponents } from 'mdx/types'
import Image, { ImageProps } from 'next/image'

// 此文件使你能够提供可在 MDX 文件中使用的自定义 React 组件。
// 你可以导入并使用任何你想要的 React 组件,包括内联样式、
// 来自其他库的组件,等等。

const components = {
  // 允许自定义内置组件,例如添加样式。
  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-components.js
import Image from 'next/image'

// 此文件使你能够提供可在 MDX 文件中使用的自定义 React 组件。
// 你可以导入并使用任何你想要的 React 组件,包括内联样式、
// 来自其他库的组件,等等。

const components = {
  // 允许自定义内置组件,例如添加样式。
  h1: ({ children }) => (
    <h1 style={{ color: 'red', fontSize: '48px' }}>{children}</h1>
  ),
  img: (props) => (
    <Image sizes="100vw" style={{ width: '100%', height: 'auto' }} {...props} />
  ),
}

export function useMDXComponents() {
  return components
}

局部样式和组件#

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

app/mdx-page/page.tsx
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} />
}
app/mdx-page/page.js
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} />
}
pages/mdx-page.tsx
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} />
}
pages/mdx-page.js
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 使用内置的布局支持。

app/mdx-page/layout.tsx
export default function MdxLayout({ children }: { children: React.ReactNode }) {
  // 在此创建任何共享布局或样式
  return <div style={{ color: 'blue' }}>{children}</div>
}
app/mdx-page/layout.js
export default function MdxLayout({ children }) {
  // 在此创建任何共享布局或样式
  return <div style={{ color: 'blue' }}>{children}</div>
}

要在 MDX 页面周围共享布局,请创建一个布局组件:

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

然后,将布局组件导入 MDX 页面,用该布局包裹 MDX 内容,并将其导出:

mdx
import MdxLayout from '../components/mdx-layout'

# 欢迎来到我的 MDX 页面!

export default function MDXPage({ children }) {
  return <MdxLayout>{children}</MdxLayout>

}

使用 Tailwind typography 插件#

如果你使用 Tailwind 为应用程序设置样式,使用 @tailwindcss/typography 插件可以让你在 markdown 文件中复用 Tailwind 配置和样式。

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

安装 Tailwind typography,并结合共享布局使用,以添加你想要的 prose 类。

app/mdx-page/layout.tsx
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>
  )
}
app/mdx-page/layout.js
export default function MdxLayout({ children }) {
  // 在此创建任何共享布局或样式
  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 页面周围共享布局,请创建一个布局组件:

components/mdx-layout.tsx
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>
  )
}
components/mdx-layout.js
export default function MdxLayout({ children }) {
  // 在此创建任何共享布局或样式
  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 内容,并将其导出:

mdx
import MdxLayout from '../components/mdx-layout'

# 欢迎来到我的 MDX 页面!

export default function MDXPage({ children }) {
  return <MdxLayout>{children}</MdxLayout>

}

Frontmatter#

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

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

content/blog-post.mdx
export const metadata = {
  author: 'John Doe',
}

# 博客文章

现在可以在 MDX 文件外部引用 metadata:

app/blog/page.tsx
import BlogPost, { metadata } from '@/content/blog-post.mdx'

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

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

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

export default function Page() {
  console.log('metadata: ', metadata)
  //=> { author: 'John Doe' }
  return <BlogPost />
}

一个常见用例是遍历一组 MDX 并提取数据。例如,从所有博客文章创建博客索引页。你可以使用 Node.js 的 fs 模块或 globby 等包来读取文章目录并提取 metadata。

小知识:

  • 使用 fs、globby 等只能在服务端进行。
  • 查看 Portfolio Starter Kit 模板,获取完整的可运行示例。

remark 和 rehype 插件#

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

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

由于 remark 和 rehype 生态仅限 ESM,你需要使用 next.config.mjs 或 next.config.ts 作为配置文件。

next.config.mjs
import remarkGfm from 'remark-gfm'
import createMDX from '@next/mdx'

/** @type {import('next').NextConfig} */
const nextConfig = {
  // 允许文件使用 .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)

在 Turbopack 中使用插件#

要在 Turbopack 中使用插件,请升级到最新版 @next/mdx 并使用字符串指定插件名称:

next.config.mjs
import createMDX from '@next/mdx'

/** @type {import('next').NextConfig} */
const nextConfig = {
  pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
}

const withMDX = createMDX({
  options: {
    remarkPlugins: [
      // 不带选项
      'remark-gfm',
      // 带选项
      ['remark-toc', { heading: 'The Table' }],
    ],
    rehypePlugins: [
      // 不带选项
      'rehype-slug',
      // 带选项
      ['rehype-katex', { strict: true, throwOnError: true }],
    ],
  },
})

export default withMDX(nextConfig)

小知识:

带有不可序列化选项的 remark 和 rehype 插件目前还不能在 Turbopack 中使用,因为 JavaScript 函数无法传递给 Rust。

深入探究:如何将 markdown 转换为 HTML?#

React 本身并不理解 markdown。markdown 纯文本需要先转换为 HTML。这可以通过 remark 和 rehype 来实现。

remark 是围绕 markdown 的工具生态系统。rehype 与之类似,但针对 HTML。例如,下面的代码片段将 markdown 转换为 HTML:

js
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('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 编译器。该编译器仍处于实验阶段,不建议用于生产环境。要使用新编译器,你需要在将 next.config.js 传递给 withMDX 时对其进行配置:

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

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

next.config.js
module.exports = withMDX({
  experimental: {
    mdxRs: {
      jsxRuntime?: string            // 自定义 jsx runtime
      jsxImportSource?: string       // 自定义 jsx import source,
      providerImportSource?: string  // 提供 `useMDXComponents` context 的模块
      mdxType?: 'gfm' | 'commonmark' // 配置解析和转换时使用哪种 mdx 语法
    },
  },
})

有用的链接#

Next.js 中文网