コンテンツへスキップ
アプリケーションの構築設定MDX

マークダウンとMDX

マークダウン は、テキストの書式設定に使用される軽量のマークアップ言語です。プレーンテキスト構文を使用して記述し、構造的に有効なHTMLに変換できます。ウェブサイトやブログのコンテンツ作成によく使用されます。

記述する…

I **love** using [Next.js](https://nextjs.dokyumento.jp/)

出力

<p>I <strong>love</strong> using <a href="https://nextjs.dokyumento.jp/">Next.js</a></p>

MDX は、マークダウンのスーパーセットであり、マークダウンファイルにJSXを直接記述できます。コンテンツ内に動的なインタラクションを追加し、Reactコンポーネントを埋め込むための強力な方法です。

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

知っておくと良い点：ポートフォリオスターターキットテンプレートを参照して、完全な動作例を確認してください。

依存関係のインストール

@next/mdxパッケージと関連パッケージを使用して、Next.jsがマークダウンと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コンポーネントを定義するために、プロジェクトのルートディレクトリにmdx-components.tsx（または.js）ファイルを作成します。例えば、pagesやappと同じレベル、または必要に応じてsrcディレクトリ内に作成します。

mdx-components.tsx
import type { MDXComponents } from 'mdx/types'
 
export function useMDXComponents(components: MDXComponents): MDXComponents {
  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を使用でき、Reactコンポーネントを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-pageルートに移動すると、レンダリングされたMDXページが表示されます。

インポートを使用

/appディレクトリ内に新しいページを作成し、MDXファイルを任意の場所に作成します。

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

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

ページ内でMDXファイルをインポートしてコンテンツを表示します。

app/mdx-page/page.tsx
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
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コンポーネントにローカルスタイルとコンポーネントを渡すことで、特定のページに適用できます。これらはグローバルスタイルとコンポーネントとマージされ、上書きされます。

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 }) {
  // Create any shared layout or styles here
  return <div style={{ color: 'blue' }}>{children}</div>
}

Tailwind typographyプラグインを使用

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

このプラグインは、Markdownなどのソースから取得したコンテンツブロックにタイポグラフィスタイルを追加するために使用できる、一連のproseクラスを追加します。

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

app/mdx-page/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>
  )
}

フロントマター

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

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

メタデータは、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などのパッケージを使用して、投稿のディレクトリを読み取り、メタデータを取り出すことができます。

知っておくと良いこと:

RemarkおよびRehypeプラグイン

必要に応じて、remarkおよびrehypeプラグインを指定してMDXコンテンツを変換できます。

たとえば、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 = {
  // 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を使用しています。

app/mdx-page-remote/page.tsx
import { MDXRemote } from 'next-mdx-remote/rsc'
 
export default async function RemoteMdxPage() {
  // MDX text - can be from a local file, database, CMS, fetch, anywhere...
  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) // 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エコシステムには、構文の強調表示、見出しへのリンク、目次（TOC）の生成などのプラグインが含まれています。

上記のように@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            // Custom jsx runtime
      jsxImportSource?: string       // Custom jsx import source,
      mdxType?: 'gfm' | 'commonmark' // Configure what kind of mdx syntax will be used to parse & transform
    },
  },
})

知っておくと良いこと:

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