如何在 Next.js 中使用 Markdown 和 MDX
了解如何配置 MDX,以便在 Markdown 文件中编写 JSX。
Markdown 是一种用于格式化文本的轻量级标记语言。它允许你使用纯文本语法编写内容,并将其转换为结构有效的 HTML。它常用于编写网站和博客上的内容。
你编写……
我**喜欢**使用 [Next.js](https://s.nodejs.cn/467aae08-be28-4a45-a7a3-7b0b687391aa)输出:
<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:
pnpm add @next/mdx @mdx-js/loader @mdx-js/react @types/mdxnpm install @next/mdx @mdx-js/loader @mdx-js/react @types/mdxyarn add @next/mdx @mdx-js/loader @mdx-js/react @types/mdxbun add @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 = {
// 配置 `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 选项:
const withMDX = createMDX({
extension: /\.(md|mdx)$/,
})添加 mdx-components.tsx 文件#
在项目根目录创建一个 mdx-components.tsx(或 .js)文件,以定义全局 MDX 组件。例如,与 pages 或 app 同级,或者在适用时放在 src 目录内。
import type { MDXComponents } from 'mdx/types'
const components: MDXComponents = {}
export function useMDXComponents(): MDXComponents {
return components
}const components = {}
export function useMDXComponents() {
return components
}小知识:
- 在 App Router 中使用
@next/mdx必须有mdx-components.tsx,否则无法工作。- 了解更多关于
mdx-components.tsx文件约定的信息。- 了解如何使用自定义样式和组件。
渲染 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在 /pages 目录中创建一个新的 MDX 页面:
my-project
|── mdx-components.(tsx/js)
├── pages
│ └── mdx-page.(mdx/md)
└── package.json你可以在这些文件中使用 MDX,甚至可以直接在 MDX 页面中导入 React 组件:
import { MyComponent } from 'my-component'
# 欢迎来到我的 MDX 页面!
这是一些**粗体**和 _斜体_ 文本。
这是一个 markdown 列表:
- 一
- 二
- 三
来看看我的 React 组件:
<MyComponent />导航到 /mdx-page 路由应显示你渲染后的 MDX 页面。
使用导入#
在 /app 目录中创建一个新页面,并在任意位置创建一个 MDX 文件:
.
├── app/
│ └── mdx-page/
│ └── page.(tsx/js)
├── markdown/
│ └── welcome.(mdx/md)
├── mdx-components.(tsx/js)
└── package.json在 /pages 目录中创建一个新页面,并在任意位置创建一个 MDX 文件:
.
├── markdown/
│ └── welcome.(mdx/md)
├── pages/
│ └── mdx-page.(tsx/js)
├── mdx-components.(tsx/js)
└── package.json你可以在这些文件中使用 MDX,甚至可以直接在 MDX 页面中导入 React 组件:
import { MyComponent } from 'my-component'
# 欢迎来到我的 MDX 页面!
这是一些**粗体**和 _斜体_ 文本。
这是一个 markdown 列表:
- 一
- 二
- 三
来看看我的 React 组件:
<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 />
}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 页面。
使用动态导入#
你可以导入动态 MDX 组件,而不是为 MDX 文件使用文件系统路由。
例如,你可以设置一个动态路由段,从单独的目录加载 MDX 组件:
generateStaticParams 可用于预渲染提供的路由。在导入之前,请检查请求的 slug 是否映射到真实文件,如果文件不存在则调用 notFound():
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 }))
}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:
## 这是一个标题
这是一个 markdown 列表:
- 一
- 二
- 三生成以下 HTML:
<h2>这是一个标题</h2>
<p>这是一个 markdown 列表:</p>
<ul>
<li>一</li>
<li>二</li>
<li>三</li>
</ul>要为 markdown 设置样式,你可以提供映射到所生成 HTML 元素的自定义组件。样式和组件可以在全局、局部以及通过共享布局来实现。
全局样式和组件#
在 mdx-components.tsx 中添加样式和组件会影响你应用程序中所有 MDX 文件。
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
}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 组件,将它们应用到特定页面。这些样式和组件会与全局样式和组件合并并覆盖它们。
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} />
}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 }) {
// 在此创建任何共享布局或样式
return <div style={{ color: 'blue' }}>{children}</div>
}export default function MdxLayout({ children }) {
// 在此创建任何共享布局或样式
return <div style={{ color: 'blue' }}>{children}</div>
}要在 MDX 页面周围共享布局,请创建一个布局组件:
export default function MdxLayout({ children }: { children: React.ReactNode }) {
// 在此创建任何共享布局或样式
return <div style={{ color: 'blue' }}>{children}</div>
}export default function MdxLayout({ children }) {
// 在此创建任何共享布局或样式
return <div style={{ color: 'blue' }}>{children}</div>
}然后,将布局组件导入 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 类。
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>
)
}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 页面周围共享布局,请创建一个布局组件:
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>
)
}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 内容,并将其导出:
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 组件一样使用导出:
export const metadata = {
author: 'John Doe',
}
# 博客文章现在可以在 MDX 文件外部引用 metadata:
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 />
}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.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 作为配置文件。
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 并使用字符串指定插件名称:
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:
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 时对其进行配置:
module.exports = withMDX({
experimental: {
mdxRs: true,
},
})mdxRs 也接受一个对象,用于配置如何转换 mdx 文件。
module.exports = withMDX({
experimental: {
mdxRs: {
jsxRuntime?: string // 自定义 jsx runtime
jsxImportSource?: string // 自定义 jsx import source,
providerImportSource?: string // 提供 `useMDXComponents` context 的模块
mdxType?: 'gfm' | 'commonmark' // 配置解析和转换时使用哪种 mdx 语法
},
},
})