Skip to main content

Markdown 和 MDX

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

编写...

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

输出:

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

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

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

添加mdx-components.tsx文件​

在项目根目录中创建一个mdx-components.tsx (或 .js) 文件，以定义全局 MDX 组件。例如，可以在与pages或app同级的位置，或者在src目录内（如果 src 目录存在）。

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

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

您需要知道:

渲染 MDX​

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

使用基于路由的文件​

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

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

在/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 页面。

使用 import​

在/app目录中创建一个新页面，并在您需要的地方创建一个 MDX file 文件:

  my-project
  ├── app
  │   └── mdx-page
  │       └── page.(tsx/js)
  ├── markdown
  │   └── welcome.(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 文件以显示内容：

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

export default function Page() {
  return <Welcome />;
}
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 文件。

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) => (
      <img
        sizes="100vw"
        style={{ width: "100%", height: "auto" }}
        {...(props as ImageProps)}
      />
    ),
    ...components,
  };
}
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.

export function useMDXComponents(components) {
  return {
    // Allows customizing built-in components, e.g. to add styling.
    h1: ({ children }) => (
      <h1 style={{ color: "red", fontSize: "48px" }}>{children}</h1>
    ),
    img: (props) => (
      <img sizes="100vw" style={{ width: "100%", height: "auto" }} {...props} />
    ),
    ...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} />;
}
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>;
}
export default function MdxLayout({ children }) {
  // Create any shared layout or styles here
  return <div style={{ color: "blue" }}>{children}</div>;
}

使用 Tailwind typography 插件​

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

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

安装 Tailwind typography并与共享布局一起使用，以添加您所需的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>
  );
}
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>
  );
}

Frontmatter​

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

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

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

# Blog post

Metadata 现在可以在 MDX 文件之外被引用：

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

export default function Page() {
  console.log('metadata': metadata)
  //=> { author: 'John Doe' }
  return <BlogPost />
}
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 来读取帖子目录并提取 metadata。

您需要知道:

  • fs、globby等只能在服务器端使用。
  • 查看Portfolio Starter Kit模板，了解完整的工作示例。

Remark 和 Rehype 插件​

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

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

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

import remarkGfm from "remark-gfm";
import createMDX from "@next/mdx";

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Configure `pageExtensions`` to include 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
  options: {
    remarkPlugins: [remarkGfm],
    rehypePlugins: [],
  },
});

// Wrap MDX and Next.js config with each other
export default withMDX(nextConfig);

远程 MDX​

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

您需要知道: 请谨慎使用。MDX 编译为 JavaScript 并在服务器上执行。您应仅从可信来源获取 MDX 内容，否则可能导致远程代码执行（RCE）。

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

import { MDXRemote } from "next-mdx-remote/rsc";

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

export default async function RemoteMdxPage() {
  // MDX text - can be from a local file, 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 编译器。该编译器仍处于实验阶段，不建议用于生产环境。要使用该编译器，您需要配置 next.config.js，此时将其传递给 withMDX：

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

您需要知道:

在使用Turbopack (next dev --turbo)处理 Markdown 和 MDX 时，这个选项是必需的。

相关链接​