Astroのブログテーマ「Fuwari」を導入し、数式を表示するためにKaTeXを利用したところ、表示が崩れる現象に遭遇した。 個人的なトラブルシューティングの記録として、現象と解決策を残しておく。
発生した現象
Markdown内で数式（$ E = mc^2 $ など）を記述すると、レンダリング自体は行われているものの、以下のように表示が崩れてしまう。
- 整形された数式が表示される。
- 元のLaTeXコードもそのまま表示される。
- これらが重なったり、並列して表示されたりして読みにくい。
通常、KaTeXはアクセシビリティ対応のために「視覚用のHTML」と「読み上げ用のMathML」などを生成するが、CSSで適切に制御しないと、これらが全て画面に出てきてしまうようだ。 つまり、CSSが正しく読み込まれていないことが疑われた。
原因：CDNへの接続タイムアウト
ブラウザの開発者ツール（Networkタブ）を確認したところ、KaTeXのCSSファイルの読み込みが failed（タイムアウト）になっていた。
ソースコード（src/layouts/Layout.astro 付近）を確認すると、デフォルトで以下のCDNが指定されていた。
<link rel="stylesheet" href="[https://cdn.staticfile.org/KaTeX/0.16.9/katex.min.css](https://cdn.staticfile.org/KaTeX/0.16.9/katex.min.css)" ...>staticfile.org について
調べてみると、staticfile.org は特定のアジア地域においては非常に高速に動作するCDNサービスのようだ。テーマの開発者の環境では、このCDNが最もパフォーマンスが良かったのだと推測される。
しかし、私の利用環境からは、ネットワーク接続経路上の問題なのか、結果としてCSSが適用されず、スタイル崩れを引き起こしていたのが原因だった。
解決策
CSSの配信元を、よりグローバルに分散され、自分の環境から安定して接続できるCDN（今回は jsDelivr）に変更することで解決した。
手順
src/layouts/Layout.astro（または<head>を管理しているファイル）を開き、リンクタグを以下のように書き換える。
変更前:
<link rel="stylesheet" href="[https://cdn.staticfile.org/KaTeX/0.16.9/katex.min.css](https://cdn.staticfile.org/KaTeX/0.16.9/katex.min.css)" integrity="..." crossorigin="anonymous">変更後:
<link rel="stylesheet" href="[https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css](https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css)" integrity="sha384-n8MVd4RsNIU0tAv4ct0nTaAbDJwPJzDEaqSD1odI+WdtXRGWt2kTvGFasHpSy3SV" crossorigin="anonymous">※integrity+属性の値はバージョン0.16.9 のものであるため、異なるバージョンを使う場合は公式サイト等でハッシュ値を確認する必要がある。面倒であれば一旦integrity 属性を外しても動作はする。
補足：本来のベストプラクティス
今回は手っ取り早く修正するためにCDNのURLを書き換えたが、Astroのようなビルドツールを使っている場合、本来はパッケージとしてインストールしてバンドルするのが最も確実かもしれない。
npm install katexとして、Astroファイル内で
import 'katex/dist/katex.min.css';とすれば、外部サーバーの状況に依存せず、確実にCSSを適用できる。次回以降はこちらの方法も検討したい。
まとめ
- 特定のブログのテーマを使用する場合、組み込まれているCDNが自分のターゲットとする地域（や自分の開発環境）から最適とは限らない。
- 「スタイルが当たらない」「アイコンが出ない」といった時は、まず外部リソースへの接続状況（Networkタブ）を疑うのが定石。