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

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

You write...

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

Output:

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

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

Next.js 既支持应用程序内的本地MDX内容，也能动态获取服务器上的远程MDX文件。其插件负责将Markdown和React组件转换为HTML，并兼容服务端组件（App Router中的默认模式）的使用。

安装依赖

@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 = {
  // 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 文件，需更新扩展选项：

next.config.mjs

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

需要注意的是：Turbopack目前不支持扩展选项，因此无法处理.md文件。

添加 mdx-components.tsx 文件

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

mdx-components.tsx

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

Good to know:

• 使用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文件以显示内容：

app/mdx-page/page.tsx

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

访问 /mdx-page 路由应显示您渲染的 MDX 页面。

使用动态导入

你可以导入动态MDX组件，而无需为MDX文件使用文件系统路由。

例如，你可以创建一个动态路由段，用于从另一个目录加载MDX组件。

generateStaticParams 可用于预渲染指定的路由。通过将 dynamicParams 设为 false，访问未在 generateStaticParams 中定义的路由将返回 404 错误。

app/blog/[slug]/page.tsx

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文件。

mdx-components.tsx

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.
 
export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    // 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)}
      />
    ),
    ...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} />
}

共享布局

要在MDX页面间共享布局，可利用App Router内置的布局支持功能。

app/mdx-page/layout.tsx

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配置与样式。

该插件添加了一组排版样式类，可用于为来自诸如markdown等来源的内容块增添印刷风格。

安装Tailwind排版插件，并与共享布局一起使用，以添加所需的文本内容。

app/mdx-page/layout.tsx

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功能，例如：

• remark-frontmatter
• 备注-MDX-前言元数据
• gray-matter

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

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

app/blog/page.tsx

TypeScript

JavaScriptTypeScript

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这样的包来读取文章目录并提取元数据。

remark和rehype插件

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

例如，你可以使用remark-gfm来支持GitHub风格的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 = {
  // 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版本，并通过字符串指定插件名称：

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: [],
    rehypePlugins: [['rehype-katex', { strict: true, throwOnError: true }]],
  },
})
 
export default withMDX(nextConfig)

Good to know:

由于无法将JavaScript函数传递至Rust，目前Turbopack尚不支持使用不具备可序列化选项的remark和rehype插件。

远程MDX

如果你的MDX文件或内容存放在其他地方，可以在服务器端动态获取。这对于存储在内容管理系统（CMS）、数据库或其他任何地方的内容非常有用。针对这一用途，社区有一个名为next-mdx-remote-client的包可供使用。

须知：请谨慎操作。MDX会编译为JavaScript并在服务器端执行。仅应从可信来源获取MDX内容，否则可能导致远程代码执行（RCE）风险。

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

app/mdx-page-remote/page.tsx

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>
}

备注与重热生态系统包含了一系列插件，用于语法高亮、标题链接、生成目录等功能。

如上所示，在使用@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            // Custom jsx runtime
      jsxImportSource?: string       // Custom jsx import source,
      mdxType?: 'gfm' | 'commonmark' // Configure what kind of mdx syntax will be used to parse & transform
    },
  },
})

有用的链接

• MDX
• @next/mdx
• remark
• rehype
• Markdoc

Previous

开发环境

Next

内存使用