Docusaurus v3 にアップグレードしました

このサイトを生成するのに使っている Docusaurus を v2 から v3 にアップグレードしました．

動機

単純に最新にしたかっただけです．古いままだとやはりメンテしづらいですから． あまり独自でいじってしまうとアップグレードしづらくなって、結局面倒なことになりかねないので、なるべく用意されている機能で拡張していくのがいいですね．私もプラグインを自作して使っていますが、大したことはしていないですし、補助的なものです．

アップグレード時の問題

MDX のバージョンが上がって v1 から一気に v3 に上がったみたいです．Markdown ファイルの制限が厳しくなり、より厳密なチェックがされるようになりました．特に影響の大きかったのは数式処理の部分をCSRにしているところで、{}がJavaScriptとして認識されてしまい、数式内のコマンドがエラーになってしまいました．これに関してはエスケープをすることで対応しましたが、数式すべてで{}をエスケープするのは置換で対応できるとはいえ面倒なので、普通にremark-math、rehype-katexプラグインを使うのが一番だと思います．この処理をしたのは数式が多いとDocusaurusのビルド時間が増えることやバンドル時の容量も増えてしまうためでした．これに関しては何らかの方法でHTMLにしたものを静的コンテンツとして扱うのがいいかなと思います．

あとは、カード形式のリンクを作成するために react-link-card を使っていたのですが、これがエラーを出すようになりました．また、このプラグインはメンテもされていないため、使わないことにしました．

もう1つ、最新のブログ投稿をトップページに表示するところで、デプロイするとエラーが表示されるものがありました．これは開発環境では発生しません．エラーは React 18 による hydration エラーで結局原因はよくわからなかったのですが、問題箇所は特定できたので対応しました．

他は特に苦労したところはありません．Node を v18 に、React も v18、TypeScript を v5 にしたことや、コンフィグファイルでESMの文法に変更したことぐらいです．

静的コンテンツの扱い

これは Docusaurus v3 でのお話ではありませんが、 デフォルトだと static フォルダに入っているものはビルド時にコピーされます．多言語（私はjaとen）をサポートしていると、その言語ごとに静的コンテンツがコピーされることを今更ながら知りました．ちょっと静的コンテンツに入れているものが大きかったのでビルドやデプロイに時間が余計に時間がかかってました．とりあえず、staticから別のフォルダに移動してビルド時にコピーするようにして対応しました．

以上です．