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

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)

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

添加 `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,
  }
}

须知:

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

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

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

渲染 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'
 
# 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 页面。

使用导入

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

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

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

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

pages/mdx-page.tsx

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

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

使用自定义样式和组件

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 组件中，将本地样式和组件应用于特定页面。这些样式和组件将与全局样式和组件合并并覆盖它们。

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

共享布局

要围绕 MDX 页面共享布局，请创建一个布局组件

components/mdx-layout.tsx

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

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

import MdxLayout from '../components/mdx-layout'
 
# Welcome to my MDX page!
 
export default function MDXPage({ children }) {
  return <MdxLayout>{children}</MdxLayout>
 
}

使用 Tailwind 排版插件

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

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

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

要围绕 MDX 页面共享布局，请创建一个布局组件

components/mdx-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>
  )
}

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

import MdxLayout from '../components/mdx-layout'
 
# Welcome to my MDX page!
 
export default function MDXPage({ children }) {
  return <MdxLayout>{children}</MdxLayout>
 
}

Frontmatter

Frontmatter 是一种类似 YAML 的键/值对，可用于存储有关页面的数据。@next/mdx 默认情况下不支持 Frontmatter，尽管有很多解决方案可以将 Frontmatter 添加到你的 MDX 内容中，例如

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

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

pages/blog.tsx

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 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 = {
  // 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)

须知:

由于无法将 JavaScript 函数传递给 Rust，尚无法将没有可序列化选项的 remark 和 rehype 插件与 Turbopack 一起使用。

远程 MDX

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

须知：请谨慎操作。MDX 编译为 JavaScript 并在服务器上执行。你应仅从受信任的来源获取 MDX 内容，否则可能会导致远程代码执行 (RCE)。

以下示例使用 next-mdx-remote

pages/mdx-page-remote.tsx

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 text - can be from a database, CMS, fetch, anywhere...
  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) // 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

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