@astrojs/ mdx

このAstroインテグレーションは、MDXコンポーネントの使用を可能にし、.mdxファイルとしてページを作成できるようにします。

なぜMDXなのか

MDXを使用すると、AstroのMarkdownコンテンツ内で変数、JSX式、コンポーネントを使用できます。MDXで作成された既存のコンテンツがある場合、このインテグレーションを使用すると、それらのファイルをAstroプロジェクトに持ち込むことができます。

インストール

Astroには、公式インテグレーションのセットアップを自動化するためのastro addコマンドが含まれています。もしよろしければ、手動でインテグレーションをインストールすることもできます。

新しいターミナルウィンドウで次のいずれかのコマンドを実行します。

npx astro add mdx

pnpm astro add mdx

yarn astro add mdx

問題が発生した場合は、GitHubで報告してください。そして、以下の手動インストール手順を試してください。

手動インストール

まず、@astrojs/mdxパッケージをインストールします。

npm install @astrojs/mdx

pnpm add @astrojs/mdx

yarn add @astrojs/mdx

次に、integrationsプロパティを使用して、インテグレーションをastro.config.*ファイルに適用します。

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [mdx()],
});

エディタの統合

VS Codeでのエディタサポートについては、公式のMDX拡張機能をインストールしてください。

他のエディタについては、MDX言語サーバーを使用してください。

使い方

標準のMDX機能の使用方法については、MDXのドキュメントを参照してください。

AstroでのMDX

MDXインテグレーションを追加すると、JSX変数、式、コンポーネントを使用してMarkdownのオーサリングが強化されます。

また、MDXでのMarkdownスタイルのフロントマターのサポートなど、標準のMDXに特別な機能が追加されます。これにより、Astroの組み込みMarkdown機能のほとんどを使用できます。

.mdxファイルは、AstroのHTMLライクな構文ではなく、MDX構文で記述する必要があります。

コンテンツコレクションでローカルのMDXを使用する

コンテンツコレクションにローカルのMDXファイルを含めるには、コレクションローダー (EN)が.mdxファイルからコンテンツをロードするように設定されていることを確認してください。

import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';
import { z } from 'astro/zod';

const blog = defineCollection({
  loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/blog" }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
  })
});

export const collections = { blog };

MDXでエクスポートされた変数を使用する

MDXは、exportステートメントを使用してMDXコンテンツに変数を追加したり、それをインポートするコンポーネントにデータをエクスポートしたりすることをサポートしています。

たとえば、MDXページまたはコンポーネントからtitleフィールドをエクスポートして、{JSX式}で見出しとして使用できます。

export const title = 'My first MDX post'

# {title}

または、importおよびimport.meta.glob()ステートメントを使用して、ページでそのエクスポートされたtitleを使用できます。

---
const matches = import.meta.glob("./posts/*.mdx", { eager: true });
const posts = Object.values(matches);
---

{posts.map((post: any) => <p>{post.title}</p>)}

エクスポートされたプロパティ

importステートメントまたはimport.meta.glob()を使用する場合、.astroコンポーネントで次のプロパティを使用できます。

file - 絶対ファイルパス（例：/home/user/projects/.../file.mdx）。
url - ページのURL（例：/ja/guides/markdown-content）。
frontmatter - ファイルのYAML/TOMLフロントマターで指定されたデータが含まれています。
getHeadings() - ファイル内のすべての見出し（<h1>から<h6>）の配列を返す非同期関数。型は{ depth: number; slug: string; text: string }[]です。各見出しのslugは、特定の見出しに対して生成されたIDに対応し、アンカーリンクに使用できます。ファイルからインポートされた見出しは含まれません。
<Content /> - ファイルの完全にレンダリングされたコンテンツを返すコンポーネント。
（任意のexport値） - MDXファイルは、exportステートメントを使用してデータをエクスポートすることもできます。

MDXでフロントマター変数を使用する

Astro MDXインテグレーションには、デフォルトでMDXでフロントマターを使用するためのサポートが含まれています。Markdownファイルと同じようにフロントマタープロパティを追加すると、これらの変数はテンプレートで使用でき、他の場所でファイルをインポートするときに名前付きプロパティとして使用できます。

---
title: 'My first MDX post'
author: 'Houston'
---

# {frontmatter.title}

Written by: {frontmatter.author}

MDXでコンポーネントを使用する

MDXインテグレーションをインストールすると、AstroコンポーネントとUIフレームワークコンポーネントの両方を、他のAstroコンポーネントと同じようにMDX（.mdx）ファイルにインポートして使用できます。

必要に応じて、UIフレームワークコンポーネントにclient:directiveを含めることを忘れないでください！

インポートおよびエクスポートステートメントの使用例については、MDXのドキュメントを参照してください。

---
title: My first post
---
import ReactCounter from '../components/ReactCounter.jsx';

I just started my new Astro blog!

Here is my counter component, working in MDX:
<ReactCounter client:load />

HTML要素へのカスタムコンポーネントの割り当て

MDXを使用すると、Markdown構文を標準のHTML要素の代わりにカスタムコンポーネントにマッピングできます。これにより、標準のMarkdown構文で記述しながら、特定の要素に特別なコンポーネントスタイルを適用できます。

たとえば、 <blockquote> コンテンツにカスタムのスタイルを適用するためのBlockquote.astroコンポーネントを作成できます。

---
const props = Astro.props;
---
<blockquote {...props} class="bg-blue-50 p-4">
  <span class="text-4xl text-blue-600 mb-2">“</span>
  <slot /> <!-- 子コンテンツには必ず`<slot/>`を追加してください！ -->
</blockquote>

カスタムコンポーネントを.mdxファイルにインポートし、標準のHTML要素をカスタムコンポーネントにマッピングするcomponentsオブジェクトをエクスポートします。

import Blockquote from '../components/Blockquote.astro';
export const components = {blockquote: Blockquote}

> この引用はカスタムのBlockquoteになります

カスタムコンポーネントとして上書きできるHTML要素の完全なリストについては、MDXのウェブサイトを参照してください。

`components`をMDXコンテンツに渡す

コンテンツコレクションによるMDXエントリなど、インポートしたMDXコンテンツを<Content />コンポーネントでレンダリングする場合、componentspropsを介してカスタムコンポーネントを渡すことができます。これらのコンポーネントは、<Content />コンポーネントで使用できるようにするために、まずインポートする必要があります。

componentsオブジェクトは、HTML要素名(h1、h2、blockquoteなど)をカスタムコンポーネントにマッピングします。また、スプレッド演算子(...)を使用して、MDXファイル自体からエクスポートされたすべてのコンポーネントを含めることもできます。これらはMDXファイルからcomponentsとしてインポートする必要があります。

Astroコンポーネントで使用するために単一ファイルから直接MDXをインポートする場合は、MDXファイルからContentコンポーネントとエクスポートされたコンポーネントの両方をインポートしてください。

---
import { Content, components } from '../content.mdx';
import Heading from '../Heading.astro';
---
<!-- #構文用のカスタム<h1>を作成し、`content.mdx`で定義されたカスタムコンポーネントを適用します。 -->
<Content components={{...components, h1: Heading }} />

MDXファイルがコンテンツコレクションのエントリである場合は、astro:contentのrender()関数を使用して<Content />コンポーネントにアクセスします。

次の例では、すべての<h1>HTML要素の代わりに使用されるカスタム見出しを、componentspropsを介し<Content />コンポーネントに渡しています。

---
import { getEntry, render } from "astro:content";
import CustomHeading from "../../components/CustomHeading.astro";
const entry = await getEntry("blog", "post-1");
if (!entry) {
  throw new Error("Entry not found");
}
const { Content } = await render(entry);
---

<Content components={{ h1: CustomHeading }} />

設定

MDXインテグレーションをインストールすると、Astroプロジェクトで.mdxファイルを使用するために設定は必要ありません。

次のオプションを使用して、MDXのレンダリング方法を設定できます。

Markdown設定から継承されたオプション
processor
extendMarkdownConfig
recmaPlugins
optimize

Markdown設定から継承されたオプション

デフォルトでは、すべてのmarkdown設定オプション (EN)は、MDXインテグレーションによって継承されます。MDXインテグレーションに渡されたオプションは、継承されたmarkdown設定を上書きします。markdownオプションの継承を完全に無視するには、extendMarkdownConfigオプションを使用してください。

以下の例は、別のシンタックスハイライトテーマを使用し、プラグインを追加し、GitHub風のMarkdownを無効にするために、MDXインテグレーションを設定しています。

import { defineConfig } from 'astro/config';
import { satteri } from '@astrojs/markdown-satteri';
import mdx from '@astrojs/mdx';
import { myMdastPlugin } from './my-satteri-plugin.mjs';

export default defineConfig({
  // ...
  markdown: {
    shikiConfig: { theme: 'rose-pine' },
  },
  integrations: [
    mdx({
      // 別のシンタックスハイライティングテーマを使用します。
      shikiConfig: { theme: 'dracula' },
      // プラグインを追加して、GitHub風のMarkdownを無効にします。
      processor: satteri({
        mdastPlugins: [myMdastPlugin()],
        features: { gfm: false },
      }),
    }),
  ],
});

オプションの完全なリストについては、Markdownオプションのリファレンス (EN)を参照してください。

`processor`

Type: MarkdownProcessor
Default: markdown.processor (EN)から継承

追加： @astrojs/mdx@6.0.0

デフォルトでは、.mdxファイルは.mdファイルと同じMarkdownプロセッサでレンダリングされます。.mdxファイルにのみ別のプロセッサ、または同じプロセッサを異なるオプションで使用したい場合は、processorを設定します。

たとえば、デフォルトのSätteriプロセッサで.mdファイルをレンダリングし続けながら、@astrojs/markdown-remarkを使ってremarkやrehypeで.mdxファイルをレンダリングするには次のようにします。

import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [
    mdx({ processor: unified() }),
  ],
});

recmaプラグインの使用

追加： @astrojs/mdx@8.0.0 New

recmaプラグインは、estree出力を直接変更します。これはMDXファイルにJavaScript変数を変更したり注入したりする場合に便利です。また、.mdファイルには影響を及ぼしません。

recmaプラグインは、Unifiedプロセッサでのみサポートされます。@astrojs/markdown-remarkからインポートしたunified()のrecmaPluginsオプションに渡してください。

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import { unified } from '@astrojs/markdown-remark';
import myRecmaPlugin from './my-recma-plugin.mjs';

export default defineConfig({
  integrations: [
    mdx({ processor: unified({ recmaPlugins: [myRecmaPlugin] }) }),
  ],
});

これらのプラグインはmarkdown.processorに対しても設定できます。MDXはデフォルトでMarkdown設定を拡張するため、.mdxファイルは引き続きこれらのプラグインを実行します。

AST Explorerを使用してestreeの出力を操作したり、estree-util-visitを使ってJavaScriptノード全体にわたる検索を試したりすることをお勧めします。

`extendMarkdownConfig`

Type: boolean
Default: true

追加： @astrojs/mdx@0.15.0

MDXは、デフォルトでプロジェクトの既存のMarkdown設定 (EN)を拡張します。個々のオプションを上書きするには、MDX設定で同等のオプションを指定します。

たとえば、.mdxファイルに別の構文ハイライターと別のプラグインのセットが必要だとします。extendMarkdownConfigをデフォルトで有効にしたまま、これらのオプションを次のように適用できます。

import { defineConfig } from 'astro/config';
import { satteri } from "@astrojs/markdown-satteri";
import mdx from "@astrojs/mdx";
import mdastPlugin1 from "./src/mdast-plugin-1";
import mdastPlugin2 from "./src/mdast-plugin-2";

export default defineConfig({
  // ...
  markdown: {
    syntaxHighlight: "prism",
    processor: satteri({ mdastPlugins: [mdastPlugin1] }),
  },
  integrations: [
    mdx({
      // Markdownの`syntaxHighlight`が上書きされ、
      // `.mdx`ファイルでは代わりにShikiが使われます。
      syntaxHighlight: "shiki",

      // `markdown.processor`は、このオプションによって`.mdx`ファイル用に上書きされます
      processor: satteri({ mdastPlugins: [mdastPlugin2] }),
    }),
  ],
});

MDXでmarkdown設定の拡張を無効にする必要がある場合もあります。この場合は、extendMarkdownConfigをfalseに設定します。

import { defineConfig } from 'astro/config';
import { satteri } from "@astrojs/markdown-satteri";
import mdx from "@astrojs/mdx";
import mdastPlugin from "./src/mdast-plugin";

export default defineConfig({
  // ...
  markdown: {
    processor: satteri({ mdastPlugins: [mdastPlugin] }),
  },
  integrations: [
    mdx({
      // Markdown設定は無視されるようになります
      extendMarkdownConfig: false,
      // デフォルトの`satteri()`プロセッサが使われます
    }),
  ],
});

`recmaPlugins`

Type: PluggableList
Default: []

追加： @astrojs/mdx@0.11.5

これらは、出力estreeを直接変更するプラグインです。これは、MDXファイルでJavaScript変数を変更または挿入する場合に便利です。

Astro v7以降、デフォルトのMarkdownプロセッサはrecmaプラグインをサポートしなくなりました。プロジェクトがこれに依存している場合、unified()プロセッサを使用できます。

AST Explorerを使用してestree出力を試したり、estree-util-visitを使用してJavaScriptノードを検索したりすることをお勧めします。

`optimize`

Type: boolean | { ignoreElementNames?: string[] }
Default: false

追加： @astrojs/mdx@0.19.5

これは、内部rehypeプラグインを介してビルドとレンダリングを高速化するためにMDX出力を最適化するためのオプションの設定です。これは、多くのMDXファイルがあり、ビルドが遅い場合に役立つ場合があります。ただし、このオプションはエスケープされていないHTMLを生成する可能性があるため、有効にした後もサイトのインタラクティブな部分が正しく機能することを確認してください。

これはデフォルトで無効になっています。MDXの最適化を有効にするには、MDXインテグレーション設定に以下を追加します。

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      optimize: true,
    }),
  ],
});

`ignoreElementNames`

Type: string[]

追加： @astrojs/mdx@3.0.0

以前はcustomComponentNamesとして知られていました。

optimizeのオプションプロパティで、MDXオプティマイザが特定の要素名を処理しないようにします。たとえば、components propsを介してインポートされたMDXコンテンツに渡されるカスタムコンポーネントなどです。

オプティマイザはコンテンツを静的文字列に積極的に変換するため、動的にレンダリングする必要があるカスタムコンポーネントが壊れてしまうため、これらのコンポーネントを最適化から除外する必要があります。

たとえば、次の意図したMDX出力は、すべての"<h1>...</h1>"の代わりに<Heading>...</Heading>です。

---
import { Content, components } from "../content.mdx";
import Heading from "../components/Heading.astro";
---

<Content components={{ ...components, h1: Heading }} />

ignoreElementNamesプロパティを使用してこれの最適化を設定するには、カスタムコンポーネントとして扱う必要があるHTML要素名の配列を指定します。

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      optimize: {
        // オプティマイザが`h1`要素を処理しないようにする
        ignoreElementNames: ['h1'],
      },
    }),
  ],
});