Markdown と MDX

Markdownは、テキストをフォーマットするための軽量マークアップ言語です。プレーンテキスト構文を使用して記述し、構造的に有効な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パッケージおよび関連パッケージは、markdownとMDXを処理できるようにNext.jsを設定するために使用されます。これはローカルファイルからデータを取得し、/pagesまたは/appディレクトリ内に.mdまたは.mdx拡張子を持つページを直接作成できるようにします。

Next.jsでMDXをレンダリングするために、これらのパッケージをインストールしてください：

Terminal

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 = {
  // markdownとMDXファイルを含めるために`pageExtensions`を設定
  pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
  // 必要に応じて、他のNext.js設定をここに追加
}
 
const withMDX = createMDX({
  // 必要に応じて、markdownプラグインをここに追加
})
 
// MDX設定とNext.js設定をマージ
export default withMDX(nextConfig)

これにより、.mdと.mdxファイルがアプリケーション内でページ、ルート、またはインポートとして機能するようになります。

`mdx-components.tsx`ファイルの追加

グローバルなMDXコンポーネントを定義するために、プロジェクトのルートにmdx-components.tsx（または.js）ファイルを作成します。例えば、pagesやappと同じレベル、または該当する場合はsrcの中に配置します。

mdx-components.tsx

TypeScript

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

補足:

mdx-components.tsxは、App Routerで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ファイルを作成します：

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

これらのファイル内でMDXを使用でき、MDXページ内で直接Reactコンポーネントをインポートすることもできます：

markdown/welcome.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/mdx-page/page.tsx

TypeScript

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

/mdx-pageルートにアクセスすると、レンダリングされたMDXページが表示されるはずです。

動的インポートの使用

ファイルシステムルーティングの代わりに、動的MDXコンポーネントをインポートすることもできます。

例えば、別のディレクトリからMDXコンポーネントを読み込む動的ルートセグメントを持つことができます：

generateStaticParamsを使用して、提供されたルートを事前レンダリングできます。dynamicParamsをfalseにマークすることで、generateStaticParamsで定義されていないルートにアクセスすると404エラーになります。

app/blog/[slug]/page.tsx

TypeScript

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const slug = (await params).slug
  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ファイルに影響します。

mdx-components.tsx

TypeScript

import type { MDXComponents } from 'mdx/types'
import Image, { ImageProps } from 'next/image'
 
// このファイルでは、MDXファイルで使用するカスタムReactコンポーネントを
// 提供できます。任意のReactコンポーネントをインポートして使用できます。
// インラインスタイル、他のライブラリからのコンポーネントなども含まれます。
 
export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    // 組み込みコンポーネントをカスタマイズできます。例えば、スタイルを追加するなど。
    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コンポーネントにローカルスタイルとコンポーネントを適用することができます。これらはグローバルスタイルとコンポーネントとマージされ、上書きされます。

app/mdx-page/page.tsx

TypeScript

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のビルトインレイアウトサポートを使用できます。

app/mdx-page/layout.tsx

TypeScript

export default function MdxLayout({ children }: { children: React.ReactNode }) {
  // 共有レイアウトやスタイルをここで作成
  return <div style={{ color: 'blue' }}>{children}</div>
}

Tailwind typographyプラグインの使用

アプリケーションのスタイル設定にTailwindを使用している場合、@tailwindcss/typographyプラグインを使用すると、Tailwindの設定とスタイルをmarkdownファイルで再利用できます。

このプラグインは、markdownのようなソースから来るコンテンツブロックに組版スタイルを追加するためのproseクラスのセットを提供します。

Tailwind typographyをインストールし、共有レイアウトで必要なproseを追加して使用します。

app/mdx-page/layout.tsx

TypeScript

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

フロントマター

フロントマターはYAMLに似たキー/値のペアリングで、ページに関するデータを保存するために使用できます。@next/mdxはデフォルトではフロントマターをサポートしていませんが、MDXコンテンツにフロントマターを追加するための多くのソリューションがあります：

@next/mdxでは、他のJavaScriptコンポーネントと同様にエクスポートを使用することができます：

content/blog-post.mdx

export const metadata = {
  author: 'John Doe',
}
 
# Blog post

メタデータをMDXファイルの外部から参照できるようになりました：

app/blog/page.tsx

TypeScript

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などはサーバーサイドでのみ使用できます。

完全な動作例については、Portfolio Starter Kitテンプレートをご覧ください。

remarkとrehypeプラグイン

オプションでremarkとrehypeプラグインを提供して、MDXコンテンツを変換することができます。

例えば、remark-gfmを使用してGitHub Flavored Markdownをサポートできます。

remarkとrehypeのエコシステムはESMのみであるため、設定ファイルとしてnext.config.mjsまたはnext.config.tsを使用する必要があります。

next.config.mjs

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にアップグレードし、文字列を使用してプラグイン名を指定します：

next.config.mjs

import createMDX from '@next/mdx'
 
/** @type {import('next').NextConfig} */
const nextConfig = {
  pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
}
 
const withMDX = createMDX({
  options: {
    remarkPlugins: [],
    rehypePlugins: [['rehype-katex', { strict: true, throwOnError: true }]],
  },
})
 
export default withMDX(nextConfig)

補足:

シリアル化可能なオプションのないremarkおよびrehypeプラグインは、JavaScriptの関数をRustに渡すことができないため、まだTurbopackで使用できません。

リモートMDX

MDXファイルやコンテンツが_他の場所_にある場合、サーバー上で動的に取得することができます。これはCMS、データベース、またはその他の場所に保存されているコンテンツに役立ちます。この用途に人気のあるコミュニティパッケージはnext-mdx-remoteです。

補足: 注意して進めてください。MDXはJavaScriptにコンパイルされ、サーバー上で実行されます。信頼できるソースからのみMDXコンテンツを取得してください。そうしないと、リモートコード実行（RCE）につながる可能性があります。

以下の例ではnext-mdx-remoteを使用しています：

app/mdx-page-remote/page.tsx

TypeScript

import { MDXRemote } from 'next-mdx-remote/rsc'
 
export default async function RemoteMdxPage() {
  // MDXテキスト - データベース、CMS、フェッチなど、どこからでも取得可能...
  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) // 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ベースのコンパイラの使用（実験的）

Next.jsはRustで書かれた新しいMDXコンパイラをサポートしています。このコンパイラはまだ実験的であり、本番環境での使用は推奨されません。新しいコンパイラを使用するには、withMDXに渡す際にnext.config.jsを設定する必要があります：

next.config.js

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

mdxRsはmdxファイルの変換方法を設定するためのオブジェクトも受け付けます。

next.config.js

module.exports = withMDX({
  experimental: {
    mdxRs: {
      jsxRuntime?: string            // カスタムjsxランタイム
      jsxImportSource?: string       // カスタムjsxインポートソース
      mdxType?: 'gfm' | 'commonmark' // どのようなmdx構文を使用して解析・変換するかを設定
    },
  },
})