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

Markdown 是一種用於格式化文字的輕量級標記語言。它允許您使用純文字語法編寫，並將其轉換為結構上有效的 HTML。它通常用於網站和部落格的內容編寫。

您編寫...

I **love** using [Next.js](https://nextjs.react.com.tw/)

輸出

<p>I <strong>love</strong> using <a href="https://nextjs.react.com.tw/">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

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 選項

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

新增 `mdx-components.tsx` 檔案

在專案的根目錄（例如，與 pages 或 app 處於同一級別，或在 src 內部，如果適用）中建立一個 mdx-components.tsx（或 .js）檔案來定義全域性 MDX 元件。

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

須知:

使用 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 檔案以顯示內容

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

導航到 /mdx-page 路由應該會顯示您渲染的 MDX 頁面。

使用動態匯入

您可以匯入動態 MDX 元件，而不是使用 MDX 檔案的檔案系統路由。

例如，您可以有一個動態路由段，它從單獨的目錄載入 MDX 元件

Route segments for dynamic MDX components

generateStaticParams 可用於預渲染提供的路由。透過將 dynamicParams 標記為 false，訪問未在 generateStaticParams 中定義的路由將返回 404。

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 檔案。

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
}

區域性樣式和元件

您可以透過將本地樣式和元件傳遞給匯入的 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} />
}

共享佈局

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

使用 Tailwind 排版外掛

如果您使用 Tailwind 為應用程式設定樣式，使用 @tailwindcss/typography 外掛將允許您在 markdown 檔案中重用 Tailwind 配置和樣式。

該外掛添加了一組 prose 類，可用於為來自 markdown 等源的內容塊新增排版樣式。

安裝 Tailwind 排版外掛，並將其與共享佈局一起使用以新增您想要的 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>
  )
}

前言

Frontmatter 是一種 YAML 鍵/值對，可用於儲存頁面的資料。@next/mdx 預設不支援 frontmatter，但有許多解決方案可以為您的 MDX 內容新增 frontmatter，例如

@next/mdx 允許您像任何其他 JavaScript 元件一樣使用匯出

元資料現在可以在 MDX 檔案之外引用

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 風格的 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 = {
  // 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 並使用字串指定外掛名稱

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 外掛，因為 JavaScript 函式無法傳遞給 Rust。

遠端 MDX

如果您的 MDX 檔案或內容位於其他位置，您可以在伺服器上動態獲取它。這對於儲存在 CMS、資料庫或任何其他位置的內容非常有用。此用途的一個社群包是 next-mdx-remote-client。

注意：請謹慎操作。MDX 會編譯成 JavaScript 並在伺服器上執行。您應該只從受信任的源獲取 MDX 內容，否則這可能導致遠端程式碼執行 (RCE)。

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

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

remark 和 rehype 生態系統包含用於語法高亮、連結標題、生成目錄等外掛。

如上所示，當使用 @next/mdx 時，您不需要直接使用 remark 或 rehype，因為它們會為您處理。我們在這裡對其進行描述是為了讓您更深入地瞭解 @next/mdx 包的底層工作原理。

使用基於 Rust 的 MDX 編譯器（實驗性）

Next.js 支援一種用 Rust 編寫的新 MDX 編譯器。這個編譯器仍處於實驗階段，不建議用於生產環境。要使用新編譯器，您需要在將它傳遞給 withMDX 時配置 next.config.js

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