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

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

您可以这样编写...

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

输出：

html

<p>I <strong>love</strong> using <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：

bash

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

配置 `next.config.mjs`

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

javascript

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 选项：

javascript

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

添加 `mdx-components.tsx` 文件

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

tsx

import type { MDXComponents } from "mdx/types";

const components: MDXComponents = {};

export function useMDXComponents(): MDXComponents {
    return components;
}

javascript

const components = {};

export function useMDXComponents() {
    return components;
}

须知：

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

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

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

渲染 MDX

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

使用基于文件系统的路由

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

App Router Only

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

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

txt

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

Pages Router Only

在 /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";

# 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 Router Only

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

txt

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

Pages Router Only

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

txt

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

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

mdx

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

App Router Only

tsx

import Welcome from "@/markdown/welcome.mdx";

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

jsx

import Welcome from "@/markdown/welcome.mdx";

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

Pages Router Only

tsx

import Welcome from "@/markdown/welcome.mdx";

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

jsx

import Welcome from "@/markdown/welcome.mdx";

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

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

App Router Only

使用动态导入

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

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

Route segments for dynamic MDX components

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

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;

jsx

export default async function Page({ params }) {
    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：

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

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.

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

javascript

import Image 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}
        />
    ),
};

export function useMDXComponents() {
    return components;
}

局部样式和组件

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

App Router Only

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

jsx

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 Router Only

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

jsx

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 Router Only

要在 MDX 页面之间共享布局，您可以使用 App Router 内置的布局支持。

tsx

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

jsx

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

Pages Router Only

要在 MDX 页面之间共享布局，请创建一个布局组件：

tsx

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

jsx

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

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

mdx

import MdxLayout from "../components/mdx-layout";

# Welcome to my MDX page!

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

}

使用 Tailwind typography 插件

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

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

安装 Tailwind typography 并结合共享布局使用，以添加您想要的 prose 样式。

App Router Only

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

jsx

export default function MdxLayout({ children }) {
    // 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>
    );
}

Pages Router Only

要在 MDX 页面之间共享布局，请创建一个布局组件：

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

jsx

export default function MdxLayout({ children }) {
    // 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 内容包裹在布局中，并导出它：

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，但有许多解决方案可以为您的 MDX 内容添加 Frontmatter，例如：

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

mdx

export const metadata = {
    author: "John Doe",
};

# Blog post

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

App Router Only

tsx

import BlogPost, { metadata } from "@/content/blog-post.mdx";

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

jsx

import BlogPost, { metadata } from "@/content/blog-post.mdx";

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

Pages Router Only

tsx

import BlogPost, { metadata } from "@/content/blog-post.mdx";

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

jsx

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 等只能在服务器端使用。

查看 Portfolio Starter Kit 模板以获取完整的工作示例。

remark 和 rehype 插件

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

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

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

javascript

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 并使用字符串指定插件名称：

javascript

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 插件尚不能与 Turbopack 一起使用，因为 JavaScript 函数无法传递给 Rust。

远程 MDX

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

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

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

App Router Only

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

jsx

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

Pages Router Only

tsx

import {
    serialize,
    type SerializeResult,
} from "next-mdx-remote-client/serialize";
import { MDXClient } from "next-mdx-remote-client";

type Props = {
    mdxSource: SerializeResult;
};

export default function RemoteMdxPage({ mdxSource }: Props) {
    if ("error" in mdxSource) {
        // either render error UI or throw `mdxSource.error`
    }
    return <MDXClient {...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({ source: mdxText });
    return { props: { mdxSource } };
}

jsx

import { serialize } from "next-mdx-remote-client/serialize";
import { MDXClient } from "next-mdx-remote-client";

export default function RemoteMdxPage({ mdxSource }) {
    if ("error" in mdxSource) {
        // either render error UI or throw `mdxSource.error`
    }
    return <MDXClient {...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({ source: mdxText });
    return { props: { mdxSource } };
}

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

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

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

remark 是围绕 Markdown 的工具生态系统。rehype 也是如此，但用于 HTML。例如，以下代码片段将 Markdown 转换为 HTML：

javascript

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：

javascript

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

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

javascript

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

有用链接

您可以这样编写...

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

输出：

html

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

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

须知：查看 Portfolio Starter Kit 模板以获取完整的工作示例。

安装依赖

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

bash

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

配置 `next.config.mjs`

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

javascript

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 选项：

javascript

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

添加 `mdx-components.tsx` 文件

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

tsx

import type { MDXComponents } from "mdx/types";

const components: MDXComponents = {};

export function useMDXComponents(): MDXComponents {
    return components;
}

javascript

const components = {};

export function useMDXComponents() {
    return components;
}

须知：

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

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

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

渲染 MDX

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

使用基于文件系统的路由

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

App Router Only

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

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

txt

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

Pages Router Only

在 /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";

# 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 Router Only

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

txt

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

Pages Router Only

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

txt

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

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

mdx

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

App Router Only

tsx

import Welcome from "@/markdown/welcome.mdx";

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

jsx

import Welcome from "@/markdown/welcome.mdx";

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

Pages Router Only

tsx

import Welcome from "@/markdown/welcome.mdx";

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

jsx

import Welcome from "@/markdown/welcome.mdx";

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

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

App Router Only

使用动态导入

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

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

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

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;

jsx

export default async function Page({ params }) {
    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：

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

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.

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

javascript

import Image 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}
        />
    ),
};

export function useMDXComponents() {
    return components;
}

局部样式和组件

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

App Router Only

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

jsx

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 Router Only

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

jsx

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 Router Only

要在 MDX 页面之间共享布局，您可以使用 App Router 内置的布局支持。

tsx

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

jsx

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

Pages Router Only

要在 MDX 页面之间共享布局，请创建一个布局组件：

tsx

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

jsx

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

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

mdx

import MdxLayout from "../components/mdx-layout";

# Welcome to my MDX page!

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

}

使用 Tailwind typography 插件

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

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

安装 Tailwind typography 并结合共享布局使用，以添加您想要的 prose 样式。

App Router Only

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

jsx

export default function MdxLayout({ children }) {
    // 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>
    );
}

Pages Router Only

要在 MDX 页面之间共享布局，请创建一个布局组件：

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

jsx

export default function MdxLayout({ children }) {
    // 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 内容包裹在布局中，并导出它：

mdx

import MdxLayout from "../components/mdx-layout";

# Welcome to my MDX page!

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

}

Frontmatter

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

mdx

export const metadata = {
    author: "John Doe",
};

# Blog post

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

App Router Only

tsx

import BlogPost, { metadata } from "@/content/blog-post.mdx";

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

jsx

import BlogPost, { metadata } from "@/content/blog-post.mdx";

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

Pages Router Only

tsx

import BlogPost, { metadata } from "@/content/blog-post.mdx";

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

jsx

import BlogPost, { metadata } from "@/content/blog-post.mdx";

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

须知：

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

查看 Portfolio Starter Kit 模板以获取完整的工作示例。

remark 和 rehype 插件

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

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

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

javascript

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 并使用字符串指定插件名称：

javascript

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 插件尚不能与 Turbopack 一起使用，因为 JavaScript 函数无法传递给 Rust。

远程 MDX

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

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

App Router Only

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

jsx

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

Pages Router Only

tsx

import {
    serialize,
    type SerializeResult,
} from "next-mdx-remote-client/serialize";
import { MDXClient } from "next-mdx-remote-client";

type Props = {
    mdxSource: SerializeResult;
};

export default function RemoteMdxPage({ mdxSource }: Props) {
    if ("error" in mdxSource) {
        // either render error UI or throw `mdxSource.error`
    }
    return <MDXClient {...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({ source: mdxText });
    return { props: { mdxSource } };
}

jsx

import { serialize } from "next-mdx-remote-client/serialize";
import { MDXClient } from "next-mdx-remote-client";

export default function RemoteMdxPage({ mdxSource }) {
    if ("error" in mdxSource) {
        // either render error UI or throw `mdxSource.error`
    }
    return <MDXClient {...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({ source: mdxText });
    return { props: { mdxSource } };
}

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

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

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

remark 是围绕 Markdown 的工具生态系统。rehype 也是如此，但用于 HTML。例如，以下代码片段将 Markdown 转换为 HTML：

javascript

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 生态系统包含用于语法高亮、链接标题、生成目录等的插件。

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

javascript

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

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

javascript

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

文档导航

安装依赖

配置 next.config.mjs

处理 .md 文件

添加 mdx-components.tsx 文件

渲染 MDX

使用基于文件系统的路由

使用导入

使用动态导入

使用自定义样式和组件

全局样式和组件

局部样式和组件

共享布局

使用 Tailwind typography 插件

Frontmatter

remark 和 rehype 插件

将插件与 Turbopack 结合使用

远程 MDX

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

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

有用链接

安装依赖

配置 next.config.mjs

处理 .md 文件

添加 mdx-components.tsx 文件

渲染 MDX

使用基于文件系统的路由

使用导入

使用动态导入

使用自定义样式和组件

全局样式和组件

局部样式和组件

共享布局

使用 Tailwind typography 插件

Frontmatter

remark 和 rehype 插件

将插件与 Turbopack 结合使用

远程 MDX

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

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

有用链接

配置 `next.config.mjs`

处理 `.md` 文件

添加 `mdx-components.tsx` 文件

配置 `next.config.mjs`

处理 `.md` 文件

添加 `mdx-components.tsx` 文件