Astroのmarkdown.remarkPlugins非推奨警告を修正する方法

非推奨（Deprecation）警告とは？#

Astroの開発サーバーを起動する際（astro dev）や本番ビルドを実行する際（astro build）、ターミナルに以下のような警告が表示されることがあります：

[astro] `markdown.remarkPlugins`, `markdown.rehypePlugins`, and `markdown.remarkRehype` are deprecated. Pass them to `unified({...})` from `@astrojs/markdown-remark` directly instead.

プロジェクトでRemarkやRehypeのプラグイン（数式レンダリング用のremark-mathやrehype-katex、見出しID生成用のrehypeHeadingIdsなど）を使用している場合、Astroはトップレベルの設定形式が非推奨となり、新しいプロセッサーアーキテクチャ（markdown.processor）へ移行することを案内しています。

この記事では、変更の背景、新しいシステムの仕組み、そして2分で完了する修正手順を分かりやすく解説します。

なぜAstroはMarkdown APIを変更したのか？#

10歳でも分かる（ELI5）たとえ話#

Astroをシステムキッチンに例えてみましょう：

• 従来: キッチンの中に1台の重厚なオーブン（Unified/Remark/Rehypeエンジン）が壁に直接固定されていました。焼き網や温度計（プラグイン）を追加したいときは、キッチンの壁全体の設定（markdown.remarkPlugins）に直接取り付ける必要がありました。
• 現在: Astroはキッチンのオーブン部分を交換可能なスロット式（markdown.processor）に刷新しました。
  • 豊富なRemark/Rehypeプラグインを活用したい場合は、Unifiedオーブン（@astrojs/markdown-remark）を差し込みます。
  • 圧倒的なビルド速度を求める場合は、Rust製の超高速なSätteriオーブン（@astrojs/markdown-satteri）を差し込むことができます。

RemarkやRehypeプラグインはUnifiedオーブン専用の部品であるため、キッチンの全体設定に直接置くのではなく、unified({...})の中にまとめて渡す構造に変更されたのです。

flowchart TD
    subgraph Legacy["従来の設定（Legacy Architecture）"]
        L_Config["astro.config.mjs (markdown.remarkPlugins / rehypePlugins)"] --> L_Engine["Astro Core (固定のUnifiedパーサー)"]
    end

    subgraph Modern["新しいプロセッサー設計 (v6.4+ / v7+)"]
        M_Config["astro.config.mjs (markdown.processor)"]
        M_Config --> M_Choice{"プロセッサーを選択"}
        M_Choice -->|unified: remarkPlugins, rehypePlugins| M_Unified["@astrojs/markdown-remark (Unified / Remark / Rehype)"]
        M_Choice -->|satteri: mdastPlugins, hastPlugins| M_Satteri["@astrojs/markdown-satteri (Rust製 Sätteri)"]
    end

新アーキテクチャのメリット#

1. コアの軽量化: Astro本体とUnifiedエコシステムの結合度が下がり、不要な場合のバンドルサイズが削減されます。
2. Rust製コンパイラの導入: Astro v7以降、設定なしで高速動作するSätteriが標準となり、ビルド性能が大幅に向上しました。
3. 設定スコープの明確化: 各プロセッサー固有のオプション（remarkPlugins, rehypePlugins, gfm, smartypants）がプロセッサー定義内に綺麗に整理されます。

修正手順（ステップ・バイ・ステップ）#

ステップ 1: @astrojs/markdown-remark のインストール#

公式パッケージ @astrojs/markdown-remark がプロジェクトにインストールされていることを確認します：

bun add @astrojs/markdown-remark
# または
npm install @astrojs/markdown-remark
# または
pnpm add @astrojs/markdown-remark

ステップ 2: astro.config.ts（または astro.config.mjs）の更新#

@astrojs/markdown-remark から unified をインポートし、プラグインを markdown.processor の中に移行します：

import { defineConfig } from 'astro/config';
import { unified, rehypeHeadingIds } from '@astrojs/markdown-remark';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkMath],
    rehypePlugins: [[rehypeKatex, {}], rehypeHeadingIds],
    smartypants: true,
    processor: unified({
      remarkPlugins: [remarkMath],
      rehypePlugins: [
        [rehypeKatex, {}],
        rehypeHeadingIds,
      ],
      gfm: true,
      smartypants: true,
    }),
    // シンタックスハイライト設定は markdown 直下に残します
    shikiConfig: {
      themes: {
        light: 'github-light',
        dark: 'github-dark',
      },
    },
  },
});

[!NOTE] コードハイライト用の shikiConfig は markdown: { ... } の直下に残ります。Markdownパーサーに関わるオプション（remarkPlugins、rehypePlugins、gfm、smartypants など）のみを processor: unified({ ... }) の中に移動します。

unified({...}) で利用できる主なオプション#

unified({...}) に渡せる一般的なオプション一覧です：

例: 脚注（Footnotes）のカスタム設定#

以前 markdown.remarkRehype で設定していた脚注のリンク表記などは、そのまま unified({...}) 内へ移動します：

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

export default defineConfig({
  markdown: {
    processor: unified({
      remarkRehype: {
        footnoteBackContent: '↩',
        footnoteLabel: '脚注',
      },
    }),
  },
});

別の選択肢: Rust製プロセッサー Sätteri を使う#

既存のRemark/Rehypeプラグインが不要で、最高速度のビルドパフォーマンスを重視する場合は、Sätteriプロセッサーを選択できます：

bun add @astrojs/markdown-satteri

astro.config.ts で以下のように設定します：

import { defineConfig } from 'astro/config';
import { satteri } from '@astrojs/markdown-satteri';

export default defineConfig({
  markdown: {
    processor: satteri({
      features: {
        gfm: true,
        smartPunctuation: true,
      },
    }),
  },
});

[!TIP] Sätteriは独自のAST形式に基づいた mdastPlugins / hastPlugins を使用します。remark-math などの既存のエコシステム資産を使いたい場合は、processor: unified({...}) を利用してください。

サードパーティ製インテグレーションとの互換性#

astro-mermaid や @astrojs/mdx などの最新インテグレーションは、自動的に config.markdown.processor を検出します。processor: unified({...}) を設定しておけば、競合することなく必要な変換プラグインが自動で統合されます。

bun run check
bun run build

設定を更新後、非推奨警告が表示されずにクリーンにビルドが成功することを確認できます。

まとめ#

• 警告の原因: Astroでトップレベルの markdown.remarkPlugins, markdown.rehypePlugins, markdown.remarkRehype が非推奨になりました。
• 解決策: @astrojs/markdown-remark から unified をインポートし、markdown.processor: unified({...}) の中にプラグインを渡します。
• 注意点: shikiConfig は markdown 直下に残し、パーサー固有の設定のみを unified({...}) に移します。

参考文献#

• Astro公式ドキュメント — Markdown in Astro ↗
• Astro設定リファレンス — markdown.processor ↗
• @astrojs/markdown-remark Package on npm ↗
• Sätteri 公式ドキュメント ↗
• Unified.js 公式サイト ↗