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に変換する処理を行い、Server Componentsでの使用もサポートしています(App Routerでデフォルト)です。
Good to know: 完全な動作例として、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を使用するように構成します:
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-components.tsx
(または.js
)ファイルを作成して、グローバルMDXコンポーネントを定義します。たとえば、pages
やapp
と同じレベル、または該当する場合はsrc
の内部に配置します。
- TypeScript
- JavaScript
import type { MDXComponents } from 'mdx/types'
export function useMDXComponents(components: MDXComponents): MDXComponents {
return {
...components,
}
}
export function useMDXComponents(components) {
return {
...components,
}
}
Good to know:
- App Routerで
@next/mdx
を使用するにはmdx-components.tsx
が必須であり、これがないと機能しません。mdx-components.tsx
ファイル規約について詳しく学ぶことができます。- カスタムスタイルとコンポーネントを使用する方法について学びます。
MDXをレンダリングする
ファイルベースのルーティングを使用するか、他のページに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}
これはいくつかの**太字**と*イタリック*のテキストです。
これはmarkdownのリストです:
- One
- Two
- Three
私のReactコンポーネントをチェックしてください:
<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コンポーネントを直接インポートすることもできます:
- mdx
import { MyComponent } from 'my-component'
# Welcome to my MDX page! \{#welcome-to-my-mdx-page}
これはいくつかの**太字**と*イタリック*のテキストです。
これはmarkdownのリストです:
- One
- Two
- Three
私のReactコンポーネントをチェックしてください:
<MyComponent />
ページ内にMDXファイルをインポートして、コンテンツを表示します:
- TypeScript
- JavaScript
import Welcome from '@/markdown/welcome.mdx'
export default function Page() {
return <Welcome />
}
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-heading}
これはmarkdownのリストです:
- One
- Two
- Three
次のHTMLが生成されます:
<h2>This is a heading</h2>
<p>これはmarkdownのリストです:</p>
<ul>
<li>One</li>
<li>Two</li>
<li>Three</li>
</ul>
markdownをスタイル付けするには、生成されたHTML要素にマッピングするカスタムコンポーネントを提供することができます。スタイルとコンポーネントは、グローバル、ローカル、および共有レイアウトで実装できます。
グローバルスタイルとコンポーネント
mdx-components.tsx
にスタイルとコンポーネントを追加すると、アプリケーション内のすべての MDXファイルに影響します。
- TypeScript
- JavaScript
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,
}
}
import Image from 'next/image'
// このファイルを使用して、MDXファイルで使用するカスタムReact
// コンポーネントを提供できます。インラインスタイルをはじめ、
// 他のライブラリからのコンポーネントなど、任意のReactコンポーネントを
// インポートして使用できます。
export function useMDXComponents(components) {
return {
// ビルトインコンポーネントのカスタマイズを許可し、例:スタイリングを追加する。
h1: ({ children }) => (
<h1 style={{ color: 'red', fontSize: '48px' }}>{children}</h1>
),
img: (props) => (
<Image
sizes="100vw"
style={{ width: '100%', height: 'auto' }}
{...props}
/>
),
...components,
}
}
ローカルスタイルとコンポーネント
インポートされたMDXコンポーネントに渡すことで、特定のページにローカルなスタイルとコンポーネントを適用できます。これらは、グローバルスタイルとコンポーネントと統合され、上書きされます。
- TypeScript
- JavaScript
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} />
}
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のビルトインレイアウトサポートを使用できます。
- TypeScript
- JavaScript
export default function MdxLayout({ children }: { children: React.ReactNode }) {
// ここで共有レイアウトやスタイルを作成してください
return <div style={{ color: 'blue' }}>{children}</div>
}
export default function MdxLayout({ children }) {
// ここで共有レイアウトやスタイルを作成してください
return <div style={{ color: 'blue' }}>{children}</div>
}
Tailwind typography pluginを使用する
アプリケーションのスタイルにTailwindを使用している場合、@tailwindcss/typography
pluginを使用すると、Tailwindの設定やスタイルをmarkdownファイルで再利用することができます。
このプラグインは、markdownなどのソースからのコンテンツブロックにタイポグラフィスタイルを追加するためのprose
クラスを追加します。
Tailwind typographyのインストールを行い、共有レイアウトでprose
を追加します。
- TypeScript
- JavaScript
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>
)
}
export default function MdxLayout({ children }) {
// ここで共有レイアウトやスタイルを作成してください
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コンポーネントのようにエクスポートを使用することを許可しています:
- mdx
export const metadata = {
author: 'John Doe',
}
# Blog post \{#blog-post}
メタデータは、MDXファイルの外部で参照することができます:
- TypeScript
- JavaScript
import BlogPost, { metadata } from '@/content/blog-post.mdx'
export default function Page() {
console.log('metadata: ', metadata)
//=> { author: 'John Doe' }
return <BlogPost />
}
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スタイルのmarkdownをサポートすることができます。
remark
とrehype
のエコシステムはESMオンリーなので、設定ファイルとしてnext.config.mjs
を使用する必要があります。
import remarkGfm from 'remark-gfm'
import createMDX from '@next/mdx'
/** @type {import('next').NextConfig} */
const nextConfig = {
// MDXファイルを含むように`pageExtensions`を構成します
pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
// 必要に応じて、他のNext.jsの設定を下に追加します
}
const withMDX = createMDX({
// 必要に応じてmarkdownプラグインをここに追加します
options: {
remarkPlugins: [remarkGfm],
rehypePlugins: [],
},
})
// MDXとNext.jsの設定を互いにラップします
export default withMDX(nextConfig)
リモートMDX
MDXファイルやコンテンツが別の場所にある場合、サーバーで動的にフェッチすることができます。これは、別のローカルフォルダーやCMS、データベースなど、他の場所に保存されたコンテンツに役立ちます。この用途に人気のあるコミュニティパッケージはnext-mdx-remote
です。
Good to know: 注意が必要です。MDX はJavaScriptにコンパイルされ、サーバーで実行されます。信頼できるソースからのみMDXコンテンツを取得する必要があります。さもないと、リモートコード実行(RCE)につながる可能性があります。
以下はnext-mdx-remote
を使用した例です:
- TypeScript
- JavaScript
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} />
}
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
を構成する必要があります:
module.exports = withMDX({
experimental: {
mdxRs: true,
},
})
mdxRs
は、mdxファイルを変換する方法を構成するためにオブジェクトも受け取ります。
module.exports = withMDX({
experimental: {
mdxRs: {
jsxRuntime?: string // カスタムjsxランタイム
jsxImportSource?: string // カスタムjsxインポートソース
mdxType?: 'gfm' | 'commonmark' // 解析および変換に使用されるmdx構文のタイプを設定
},
},
})
Good to know:
markdownとMDXをTurbopack(
next dev --turbopack
)を使用して処理する場合、このオプションが必要です。