@astrojs/ mdx

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

なぜMDXなのか

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

インストール

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

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

npm

npx astro add mdx

pnpm

pnpm astro add mdx

Yarn

yarn astro add mdx

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

手動インストール

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

npm

npm install @astrojs/mdx

pnpm

pnpm add @astrojs/mdx

Yarn

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機能 (EN)のほとんどを使用できます。

.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 => <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のウェブサイトを参照してください。

:::noteMDXファイル内で定義およびエクスポートされたカスタムコンポーネントは、常にインポートしてから 、componentsプロパティを介して<Content />コンポーネントに渡す必要があります。:::

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');
const { Content } = await render(entry);
---
<Content components={{ h1: CustomHeading }} />

設定

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

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

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

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

すべてのmarkdown設定オプション (EN)は、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,
    }),
  ],
});

:::cautionMDXは、remarkおよびrehypeプラグインを文字列として渡すことをサポートしていません。代わりに、プラグイン関数をインストール、インポート、および適用する必要があります。:::

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

extendMarkdownConfig

Type: boolean
Default: true

追加： @astrojs/mdx@0.15.0

MDXは、デフォルトでプロジェクトの既存のMarkdown設定 (EN)を拡張します。個々のオプションを上書きするには、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

Type: PluggableList
Default: []

追加： @astrojs/mdx@0.11.5

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

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 '../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'],
      },
    }),
  ],
});

MDXファイルがexport const components = { ... }を使用してカスタムコンポーネントを設定する場合、このオプションを手動で設定する必要はありません。オプティマイザはそれらを自動的に検出します。

例

• Astro MDXスターターテンプレートは、AstroプロジェクトでMDXファイルを使用する方法を示しています。

他のインテグレーション

UIフレームワーク

• 

  @astrojs/alpinejs

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

SSRアダプター

• 

  @astrojs/cloudflare

• 

  @astrojs/netlify

• 

  @astrojs/node

• 

  @astrojs/vercel

その他

• 

  @astrojs/db

• 

  @astrojs/markdoc

• 

  @astrojs/mdx

• 

  @astrojs/partytown

• 

  @astrojs/sitemap