Menu

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 に変換し、Server Components（App Router のデフォルト）での使用もサポートします。

補足: 完全に動作する例については、ポートフォリオ スターター キット テンプレートを参照してください。

依存関係のインストール

@next/mdx パッケージと関連パッケージは、Next.js が Markdown と MDX を処理できるように設定するために使用されます。ローカルファイルからデータを取得し、/pages または /app ディレクトリ内で .md または .mdx 拡張子のページを直接作成できます。

MDX を Next.js でレンダリングするには、以下のパッケージをインストールします：

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.js
export function useMDXComponents(components) {
  return {
    ...components,
  }
}

補足：

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 ページが表示されます。

カスタムスタイルとコンポーネントの使用

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-components.js
import Image from 'next/image'
 
// このファイルでは、MDX ファイルで使用するカスタム React コンポーネントを
// 提供できます。インラインスタイル、他のライブラリのコンポーネントなど、
// 任意の React コンポーネントをインポートして使用できます。
 
export function useMDXComponents(components) {
  return {
    // スタイル追加などのために、組み込みコンポーネントをカスタマイズできます。
    h1: ({ children }) => (
      <h1 style={{ color: 'red', fontSize: '48px' }}>{children}</h1>
    ),
    img: (props) => (
      <Image
        sizes="100vw"
        style={{ width: '100%', height: 'auto' }}
        {...props}
      />
    ),
    ...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タイポグラフィプラグインの使用

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

このプラグインは、マークダウンなどのソースから来るコンテンツブロックに、タイポグラフィスタイルを追加できるproseクラスのセットを追加します。

Tailwindタイポグラフィをインストールし、共有レイアウトと共に使用して、必要な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',
}
 
# ブログ投稿

メタデータは現在、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 の fs モジュールやglobbyなどのパッケージを使用して、投稿のディレクトリを読み取り、メタデータを抽出できます。

補足:

RemarkとRehypeプラグイン

オプションで、MDXコンテンツを変換するためのremarkおよびrehypeプラグインを提供できます。

例えば、GitHub Flavored Markdownをサポートするためにremark-gfmを使用できます。

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 = {
  // MDXファイルを含むように`pageExtensions`を設定
  pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
  // オプションで、その他のNext.js設定を追加
}
 
const withMDX = createMDX({
  // 必要に応じて、マークダウンプラグインをここに追加
  options: {
    remarkPlugins: [remarkGfm],
    rehypePlugins: [],
  },
})
 
// MDXとNext.js設定を相互にラップ
export default withMDX(nextConfig)

リモート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が表示されます。

ディープダイブ: マークダウンをHTMLに変換する方法

Reactはネイティブでマークダウンを理解しません。マークダウンのプレーンテキストは最初にHTMLに変換される必要があります。これはremarkとrehypeで実現できます。

remarkはマークダウン周りのツールのエコシステムです。rehypeもHTML用の同様のものです。例えば、次のコードスニペットはマークダウンを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) // マークダウンASTに変換
    .use(remarkRehype) // HTMLのASTに変換
    .use(rehypeSanitize) // HTMLの入力をサニタイズ
    .use(rehypeStringify) // ASTをシリアライズされたHTMLに変換
    .process('こんにちは、Next.js！')
 
  console.log(String(file)) // <p>こんにちは、Next.js！</p>
}

remarkとrehypeのエコシステムには、シンタックスハイライト、見出しのリンク、目次の生成などのプラグインが含まれています。

上記のように@next/mdxを使用する場合、直接remarkやrehypeを使用する 必要はありません。@next/mdxパッケージが内部で処理するためです。ここでは、@next/mdxパッケージが下で何をしているかをより深く理解するために説明しています。

Rust製MDXコンパイラの使用（実験的）

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シンタックスの種類
    },
  },
})

補足:

このオプションは、Turbopack（next dev --turbopack）を使用しながらマークダウンとMDXを処理する場合に必要です。

参考リンク