Next.jsで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のデフォルト)での使用もサポートしています。
補足: 完全な動作例については、ポートフォリオスターターキットテンプレートをご覧ください。
依存関係のインストール
@next/mdx
パッケージおよび関連パッケージは、Next.jsがmarkdownと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を使用するように設定します:
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)
これにより、.mdx
ファイルをアプリケーション内のページ、ルート、またはインポートとして機能させることができます。
.md
ファイルの処理
デフォルトでは、next/mdx
は.mdx
拡張子を持つファイルのみをコンパイルします。webpackで.md
ファイルを処理するには、extension
オプションを更新してください:
const withMDX = createMDX({
extension: /\.(md|mdx)$/,
})
補足: Turbopackは現在
extension
オプションをサポートしていないため、.md
ファイルをサポートしていません。
mdx-components.tsx
ファイルの追加
グローバルMDXコンポーネントを定義するために、プロジェクトのルートにmdx-components.tsx
(または.js
)ファイルを作成します。例えば、pages
やapp
と同じレベル、または該当する場合はsrc
の中に配置します。
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のレンダリング
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'
# MDXページへようこそ!
これは**太字**と_イタリック_のテキストです。
これはmarkdownのリストです:
- 一つ目
- 二つ目
- 三つ目
私のReactコンポーネントをチェックしてください:
<MyComponent />
/mdx-page
ルートにアクセスすると、レンダリングされたMDXページが表示されます。
インポートの使用
/app
ディレクトリ内に新しいページを作成し、任意の場所にMDXファイルを配置します:
.
├── app/
│ └── mdx-page/
│ └── page.(tsx/js)
├── markdown/
│ └── welcome.(mdx/md)
├── mdx-components.(tsx/js)
└── package.json
これらのファイル内でMDXを使用し、MDXページ内で直接Reactコンポーネントをインポートすることもできます:
import { MyComponent } from 'my-component'
# MDXページへようこそ!
これは**太字**と_イタリック_のテキストです。
これはmarkdownのリストです:
- 一つ目
- 二つ目
- 三つ目
私のReactコンポーネントをチェックしてください:
<MyComponent />
コンテンツを表示するために、ページ内でMDXファイルをインポートします:
import Welcome from '@/markdown/welcome.mdx'
export default function Page() {
return <Welcome />
}
/mdx-page
ルートにアクセスすると、レンダリングされたMDXページが表示されます。
動的インポートの使用
ファイルシステムルーティングの代わりに、動的MDXコンポーネントをインポートすることができます。
例えば、別のディレクトリからMDXコンポーネントをロードする動的ルートセグメントを持つことができます:
generateStaticParams
を使用して、提供されたルートを事前レンダリングできます。dynamicParams
をfalse
にすることで、generateStaticParams
で定義されていないルートにアクセスすると404エラーになります。
export default async function Page({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
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を書くと:
## これは見出しです
これはmarkdownのリストです:
- 一つ目
- 二つ目
- 三つ目
次のHTMLが生成されます:
<h2>これは見出しです</h2>
<p>これはmarkdownのリストです:</p>
<ul>
<li>一つ目</li>
<li>二つ目</li>
<li>三つ目</li>
</ul>
markdownにスタイルを適用するには、生成されたHTML要素にマッピングするカスタムコンポーネントを提供できます。スタイルとコンポーネントはグローバル、ローカル、共有レイアウトで実装できます。
グローバルスタイルとコンポーネント
mdx-components.tsx
にスタイルとコンポーネントを追加すると、アプリケーション内の_すべての_MDXファイルに影響します。
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コンポーネントにローカルスタイルとコンポーネントを適用できます。これらはグローバルスタイルとコンポーネントとマージされ、それらを上書きします。
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の組み込みレイアウトサポートを使用できます。
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
を追加してください。
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コンポーネントと同様にエクスポートを使用できます:
export const metadata = {
author: 'John Doe',
}
# ブログ投稿
メタデータはMDXファイル外で参照できるようになります:
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
などはサーバーサイドでのみ使用できます。- 完全な動作例については、ポートフォリオスターターキットテンプレートをご覧ください。
remarkとrehypeのプラグイン
オプションでremarkとrehypeのプラグインを提供して、MDXコンテンツを変換できます。
例えば、remark-gfm
を使用してGitHub Flavored Markdownをサポートできます。
remarkとrehypeのエコシステムはESMのみであるため、設定ファイルとしてnext.config.mjs
またはnext.config.ts
を使用する必要があります。
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
にアップグレードし、文字列を使用してプラグイン名を指定します:
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-client
があります。
補足: 慎重に進めてください。MDXはJavaScriptにコンパイルされ、サーバー上で実行されます。信頼できるソースからのみMDXコンテンツを取得してください。そうでなければ、リモートコード実行(RCE)につながる可能性があります。
以下の例ではnext-mdx-remote-client
を使用しています:
import { MDXRemote } from 'next-mdx-remote-client/rsc'
export default async function RemoteMdxPage() {
// MDXテキスト - データベース、CMS、fetch、どこからでも取得可能...
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
パッケージが内部で行っていることです。ここでは@next/mdx
パッケージの仕組みをより深く理解するために説明しています。
Rust製MDXコンパイラの使用(実験的)
Next.jsはRustで書かれた新しいMDXコンパイラをサポートしています。このコンパイラはまだ実験的で、本番環境での使用は推奨されていません。新しいコンパイラを使用するには、withMDX
に渡す際にnext.config.js
を設定する必要があります:
module.exports = withMDX({
experimental: {
mdxRs: true,
},
})
mdxRs
はmdxファイルの変換方法を設定するオブジェクトも受け付けます。
module.exports = withMDX({
experimental: {
mdxRs: {
jsxRuntime?: string // カスタムjsxランタイム
jsxImportSource?: string // カスタムjsxインポートソース
mdxType?: 'gfm' | 'commonmark' // 解析と変換に使用するmdx構文の種類を設定
},
},
})