MarkdownとMDX

Markdown は、テキストをフォーマットするために使用される軽量なマークアップ言語です。プレーンテキストの構文を使用して記述し、構造的に有効な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 はMarkdownのスーパーセットで、JSX をMarkdownファイルに直接記述できます。これは、動的なインタラクティビティを追加し、Reactコンポーネントをコンテンツ内に埋め込む強力な方法です。

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

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

依存関係のインストール

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

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`はApp Routerで`@next/mdx`を使用するために**必須**であり、これがないと動作しません。

`mdx-components.tsx`ファイル命名規則について詳しくはこちら。

カスタムスタイルとコンポーネントを使用する方法を学ぶ。

MDXのレンダリング

MDXは、Next.jsのファイルベースルーティングを使用するか、MDXファイルを他のページにインポートしてレンダリングできます。

ファイルベースルーティングの使用

ファイルベースルーティングを使用する場合、MDXページを他のページと同様に使用できます。

`/pages`ディレクトリ内に新しいMDXページを作成します。

  my-project
  |── mdx-components.(tsx/js)
  ├── pages
  │   └── mdx-page.(mdx/md)
  └── 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ページが表示されます。

インポートの使用

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

  .
  ├── markdown/
  │   └── welcome.(mdx/md)
  ├── pages/
  │   └── mdx-page.(tsx/js)
  ├── mdx-components.(tsx/js)
  └── package.json

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

コンテンツを表示するために、ページ内でMDXファイルをインポートします。

pages/mdx-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コンポーネントにローカルスタイルとコンポーネントを渡すことで、特定のページに適用できます。これらは、グローバルスタイルとコンポーネントを結合し、オーバーライドします。

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

共有レイアウト

MDXページ間でレイアウトを共有するには、レイアウトコンポーネントを作成します。

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 typographyプラグインの使用

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

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

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

フロントマター

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

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

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

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の`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 = {
  // Allow .mdx extensions for 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: [],
  },
})
 
// Combine MDX and Next.js config
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プラグインは、Turbopackではまだ使用できません。これは、JavaScript関数をRustに渡すことができないためです。

リモート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 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コンパイラをサポートしています。このコンパイラはまだ実験的であり、本番環境での使用は推奨されません。新しいコンパイラを使用するには、`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
    },
  },
})