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のデフォルト)での使用もサポートしています。
補足: 完全な動作例については、Portfolio Starter Kitテンプレートをご覧ください。
依存関係のインストール
@next/mdx
パッケージおよび関連パッケージは、markdownとMDXを処理できるようにNext.jsを設定するために使用されます。これはローカルファイルからデータを取得し、/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)
これにより、.md
と.mdx
ファイルがアプリケーション内でページ、ルート、またはインポートとして機能するようになります。
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で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'
# 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コンポーネントをインポートすることもできます:
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ファイルをインポートします:
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).slug
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を記述すると:
## 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ファイルに影響します。
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',
}
# Blog post
メタデータをMDXファイルの外部から参照できるようになりました:
import BlogPost, { metadata } from '@/content/blog-post.mdx'
export default function Page() {
console.log('metadata: ', metadata)
//=> { author: 'John Doe' }
return <BlogPost />
}
一般的なユースケースとして、MDXのコレクションをイテレートしてデータを抽出する場合があります。例えば、すべてのブログ投稿からブログインデックスページを作成する場合です。Node.jsの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
を使用する必要があります。
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
です。
補足: 注意して進めてください。MDXはJavaScriptにコンパイルされ、サーバー上で実行されます。信頼できるソースからのみMDXコンテンツを取得してください。そうしないと、リモートコード実行(RCE)につながる可能性があります。
以下の例ではnext-mdx-remote
を使用しています:
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ベースのコンパイラの使用(実験的)
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構文を使用して解析・変換するかを設定
},
},
})