Docusaurus v3 対応（v2 からの移行）

公式の移行記事（ブログ）

Preparing your site for Docusaurus v3 | Docusaurus
https://docusaurus.io/blog/preparing-your-site-for-docusaurus-v3

大きなトピックとしては

• MDX v1 → v2 v3 になることでの影響
• Node.js >= 18.0
• React >= 18.0

これらによる build 時エラー、開発モードの live server、build 後のリソースでの影響各種。

確認時の Docusaurus バージョンは v3.0.0-beta.0 と v3.0.0-rc.0

細かくは記載しないが rc.0 になって、beta.0 のときに出ていたコンソールエラーが解消されたものがあった。

あと単純に、有志提供のプラグインがまだ v3 に対応していない…
Commit 履歴や Issue を見る限り活動が停止していて怪しいものも… 😭

手元で利用しているものだと以下とか。

Add support for docusaurus v3 · Issue #194 · cmfcmf/docusaurus-search-local
https://github.com/cmfcmf/docusaurus-search-local/issues/194

条件が複雑すぎて根本原因はよくわかっていないが sidebar.js で type: "generated-index" を使わずに手製で index ページを用意してたところ、Runtime エラーが発生していた。

それをやっていたからといって必ずエラーになるわけでもないだろうから、本当によくわからない。

Uncought runtime errors:

ERROR
Hook useDocsVersion is called outside the <DocsVersionProvider>.
ReactContextError
    at useDocsVersion (webpack-internal:///./node_modules/@docusaurus/theme-common/lib/contexts/docsVersion.js:19:128)
    ....

バージョン機能は一切利用してないので意味がわからず、一旦 v3.0.0-beta.0 で docusaurus new したものから差分をじわじわ攻めていって解消する部分を見つけていくという泥臭いことをした。

Preparing your site for Docusaurus v3 | Docusaurus に記載のある npx docusaurus-mdx-checker は v2 リソース時点で実行して、エラー解消まで行っていたけど、それ以外で結構エラーへの対応が必要だった。

footnotes のデザインが変わっていた。

v2

hr で区切られている。

v3-beta

見出し？で区切られている。TOC には載らない。

なんか記号がおかしいな😇

日本語指定しているのに英語で表示されてるのは、対象の翻訳がまだ入っていないのだと思われる。

v3.0.0 無印リリース済みだけど、sidebar.js で type: "html" が正常に表示されていない件は Issue になった。

v3 html sidebar links don't work · Issue #9483 · facebook/docusaurus
https://github.com/facebook/docusaurus/issues/9483