メインコンテンツまでスキップ

Markdown and 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のスーパーセットであり、JSXをMarkdownファイル内で直接書くことができます。コンテンツ内に動的なインタラクティビティを追加し、Reactコンポーネントを埋め込む強力な方法です。

Next.jsは、アプリケーション内のローカルMDXコンテンツと、サーバー上で動的にフェッチされるリモートMDXファイルの両方をサポートできます。Next.jsプラグインは、MarkdownとReactコンポーネントをHTMLに変換する処理を行い、Server Components（App Routerでのデフォルト）での使用もサポートしています。

Good to know: 完全な動作例としてPortfolio Starter Kitテンプレートを参照してください。

依存関係をインストールする​

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

Next.jsでMDXをレンダリングするためにこれらのパッケージをインストールします:

Terminal
npm install @next/mdx @mdx-js/loader @mdx-js/react @types/mdx

next.config.mjsを設定する​

プロジェクトのrootでnext.config.mjsファイルを更新し、MDXを使用するように設定します:

next.config.mjs
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)

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

mdx-components.tsxファイルを追加する​

プロジェクトのrootに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,
  }
}

Good to know:

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! \{#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! \{#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
import Welcome from '@/markdown/welcome.mdx'

export default function Page() {
  return <Welcome />
}

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

動的インポートを使用する​

ファイルシステムルーティングを使用せずに動的MDXコンポーネントをインポートできます。

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

動的MDXコンポーネントのルートセグメント動的MDXコンポーネントのルートセグメント

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

app/blog/[slug]/page.tsx
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

Good to know: インポート時に.mdxファイル拡張子を指定してください。モジュールパスエイリアス（例: @/content）を使用する必要はありませんが、インポートパスを簡素化します。

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

MarkdownはレンダリングされるとネイティブのHTML要素にマッピングされます。例えば、次のMarkdownを書くと:

## This is a heading \{#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'

// このファイルでは、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
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
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
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>
  )
}

Frontmatter​

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

@next/mdxは、他のJavaScriptコンポーネントと同様にエクスポートを使用することを許可しています:

content/blog-post.mdx
export const metadata = {
  author: 'John Doe',
}

# Blog post \{#blog-post}

メタデータは、MDXファイルの外部で参照できます:

app/blog/page.tsx
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のようなパッケージを使用して、投稿のディレクトリを読み取り、メタデータを抽出できます。

Good to know:

  • fs、globbyなどの使用はサーバーサイドでのみ可能です。
  • 完全な動作例としてPortfolio Starter Kitテンプレートを参照してください。

remarkとrehypeプラグイン​

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

例えば、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 = {
  // ファイルの.mdおよび.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)

Good to know:

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

リモートMDX​

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

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

次の例ではnext-mdx-remoteを使用しています:

app/mdx-page-remote/page.tsx
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ベースの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構文の種類を設定
    },
  },
})