建置您的應用程式 (Building Your Application)設定 (Configuring)MDX

Markdown 和 MDX (Markdown and MDX)

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

您撰寫...

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

輸出

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

MDX 是 Markdown 的超集，讓您可以在 Markdown 檔案中直接撰寫 JSX。這是一種在您的內容中添加動態互動性和嵌入 React 元件的強大方法。

Next.js 可以支援應用程式內的本地 MDX 內容，以及在伺服器上動態擷取的遠端 MDX 檔案。Next.js 外掛程式會將 Markdown 和 React 元件轉換為 HTML，包含在伺服器元件（App Router 中的預設值）中的使用支援。

貼心小提醒：查看作品集入門套件範本，以取得完整的範例。

安裝 dependencies（相依套件）

@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 的**必要**條件，沒有它將無法運作。

進一步了解 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 頁面。

使用匯入

  my-project
  ├── pages
  │   └── mdx-page.(tsx/js)
  ├── markdown
  │   └── welcome.(mdx/md)
  |── 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 頁面。

使用自訂樣式和元件

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

共用佈局

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 元件一樣使用匯出（exports）

現在可以在 MDX 檔案外部參考詮釋資料（Metadata）。

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.js 的 fs 模組（英文）或 globby（英文）之類的套件來讀取文章目錄並提取詮釋資料。

注意事項:

使用 fs、globby 等僅限在伺服器端使用。

查看作品集入門套件範本以獲得完整的工作範例。

Remark 與 Rehype 外掛

您可以選擇性地提供 remark 和 rehype 外掛來轉換 MDX 內容。

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

由於 remark 和 rehype 生態系統僅支援 ESM，您需要使用 next.config.mjs 作為設定檔。

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

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 local file, 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 編譯器。此編譯器仍處於實驗階段，不建議用於生產環境。要使用新的編譯器，您需要在將 next.config.js 傳遞給 withMDX 時進行設定。

next.config.js

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

mdxRs 也接受一個物件來設定如何轉換 mdx 檔案。