@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ファイルを含めるには、コレクションローダーが.mdxファイルからコンテンツをロードするように設定されていることを確認してください。

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

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

インポートされたMDXを使用したカスタムコンポーネント

インポートされたMDXコンテンツをレンダリングする場合、カスタムコンポーネントをcomponentsプロップを介して渡すことができます。

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

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

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

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

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

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

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

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

設定

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

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

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

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

すべてのmarkdown設定オプションは、MDXインテグレーションで個別に設定できます。これには、remarkおよびrehypeプラグイン、構文ハイライトなどが含まれます。オプションは、Markdown設定のオプションにデフォルト設定されます（これを変更するには、extendMarkdownConfigオプションを参照してください）。

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import remarkToc from 'remark-toc';
import rehypePresetMinify from 'rehype-preset-minify';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      syntaxHighlight: 'shiki',
      shikiConfig: { theme: 'dracula' },
      remarkPlugins: [remarkToc],
      rehypePlugins: [rehypePresetMinify],
      remarkRehype: { footnoteLabel: 'Footnotes' },
      gfm: false,
    }),
  ],
});

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

`extendMarkdownConfig`

Type: boolean
Default: true

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

たとえば、GitHub-Flavored Markdownを無効にし、MDXファイルに別のremarkプラグインのセットを適用する必要があるとします。extendMarkdownConfigをデフォルトで有効にしたまま、これらのオプションを次のように適用できます。

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

export default defineConfig({
  // ...
  markdown: {
    syntaxHighlight: 'prism',
    remarkPlugins: [remarkPlugin1],
    gfm: true,
  },
  integrations: [
    mdx({
      // Markdownから継承された`syntaxHighlight`

      // Markdownの`remarkPlugins`は無視され、
      // `remarkPlugin2`のみが適用されます。
      remarkPlugins: [remarkPlugin2],
      // `gfm`は`false`に上書きされます
      gfm: false,
    }),
  ],
});

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

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

export default defineConfig({
  // ...
  markdown: {
    remarkPlugins: [remarkPlugin1],
  },
  integrations: [
    mdx({
      // Markdown設定は無視されます
      extendMarkdownConfig: false,
      // `remarkPlugins`は適用されません
    }),
  ],
});

`recmaPlugins`

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

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

`optimize`

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

これは、内部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プロップを介してインポートされたMDXコンテンツに渡されるカスタムコンポーネントなどです。

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

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

---
import { Content, components } from '../content.mdx';
import Heading from '../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'],
      },
    }),
  ],
});