AstroのremarkPlugins追加で脚注(GFM)が動かなくなる問題と解決策

AstroやStarlightで数式を表示するために remark-math などのカスタムプラグインを導入したところ、これまで使えていた脚注（[^1]）やテーブルが突然機能しなくなるという現象に遭遇しました。

この記事では、その原因と正しい設定方法、そしてビルド環境によるエラーの差異についてまとめます。

原因：デフォルトプラグインの上書き

Astroは標準で、以下の2つの便利なMarkdownプラグインを内蔵しています。

GitHub-flavored Markdown (GFM)：脚注やテーブル、取り消し線などをサポート
SmartyPants：引用符やダッシュなどの記号を綺麗に組版

しかし、astro.config.mjs でカスタムプラグイン（例：remark-math）を配列で直接指定すると、Astro（特にMDXやStarlightの環境下）が「ユーザーが独自の完全なプラグイン構成を上書き設定した」とみなし、これら2つのデフォルトプラグインがオフになってしまうことがあります。

結果として、脚注の記法である [^1]: 注釈内容 がただのテキストリンクとしてパースされてしまい、想定通りに機能しなくなります。

解決策：明示的な追加

この問題を解決するには、デフォルトで有効になっていたはずの remark-gfm と remark-smartypants を手動でインストールし、配列の中に明示的に追加します。

npm install remark-gfm remark-smartypants

import remarkMath from 'remark-math';
import remarkGfm from 'remark-gfm';
import remarkSmartypants from 'remark-smartypants';

export default defineConfig({
  markdown: {
    // デフォルト機能も明示的に配列へ入れる
    remarkPlugins: [remarkGfm, remarkSmartypants, remarkMath],
  }
});

余談：ローカルとCI（GitHub Actions）での挙動の違い

この脚注パースの失敗に気づくきっかけとなったのが、Starlightのリンク切れチェッカーである starlight-links-validator でした。

脚注が正常にパースされず [^1]: という謎のテキストリンク扱いになった結果、GitHub Actions上のビルド（Linux環境）では「リンク切れ」としてエラーになりました。しかし不思議なことに、ローカル（Windows環境）でのビルドは成功していました。

この差異の理由は、プラグインのバグによるものです。

Windows環境：ファイルパスにバックスラッシュ（\）が使われるため、リンクチェッカーの照合ロジック（スラッシュ / 前提）がうまく働かず、エラーを「見逃して」いた。
Linux環境 (GitHub Actions)：ファイルパスがスラッシュ（/）のため、照合が完璧に機能し、正しくエラーを検知してビルドを落とした。

このように、プラグインによるデフォルト機能の消失と、OS間のパス区切り文字の違いが重なることで、トラブルシューティングが少しややこしくなっていました。

他の記事を探す