Docusaurus v3への移行

[chvmvd]

Docusaurus 3.0.0に移行

Docursaurus 3.0.0がリリースされたので、移行する。
https://github.com/facebook/docusaurus/releases/tag/v3.0.0
https://docusaurus.io/docs/migration/v3

影響する変更

依存関係の更新

https://docusaurus.io/docs/migration/v3#upgrading-dependencies

Node.js 18への更新

https://docusaurus.io/docs/migration/v3#nodejs-v180

Admonitionの変更

https://docusaurus.io/docs/migration/v3#admonition-warning

React 18への移行によりimport React from 'react';が不要

https://docusaurus.io/docs/migration/v3#automatic-jsx-runtime

設定ファイルのESMへの移行

https://docusaurus.io/docs/migration/v3#esm-and-typescript-configs

拡張子を.mdxに移行

https://docusaurus.io/docs/migration/v3#using-the-mdx-extension

math関係のパッケージを更新

https://docusaurus.io/docs/migration/v3#upgrading-math-packages

MDX文法への完全な移行

https://docusaurus.io/docs/migration/v3#turn-off-mdx-v1-compat

HTMLコメントからMDXコメントへの移行

https://docusaurus.io/docs/migration/v3#comments-option

Admonitionの文法の移行

https://docusaurus.io/docs/migration/v3#admonitions-option

MDX v1からv3への移行

MDX checker CLI
https://github.com/slorber/docusaurus-mdx-checker

MDX v1からv2への移行

https://mdxjs.com/migrating/v2/
かなり大きな変更がある。次がこのリポジトリに影響する変更

• JSXとMarkdownの間の空行が不要になった。（https://mdxjs.com/migrating/v2/#jsx）
• JSX内でMarkdownのインデントが可能になった。（https://mdxjs.com/migrating/v2/#jsx）

MDX v2からv3への移行

https://mdxjs.com/migrating/v3/
大きな変更はない。

[chvmvd]

やること

移行への準備

• Node.js 18への更新 Update version of Node.js #532
• 拡張子を.mdxに移行 Migrate file extension from .md to .mdx #534
• MDX checker CLIを使いながら、移行のためにMDXの記法を修正 Remove strong prop from Term component #540

移行

• 依存関係の更新 Migrate to Docusaurus 3.0.0 #541
• math関係のパッケージを更新 Migrate to Docusaurus 3.0.0 #541

移行後

• JSXとMarkdownの間の空行が不要になった。Remove indent in JSX #543
• JSX内でMarkdownのインデントが可能になった。Remove indent in JSX #543
• Admonitionの変更 Migrate admonition from caution to warning #547
• React 18への移行によりimport React from 'react';が不要 Remove import of React #546
• MDX文法への完全な移行
  • HTMLコメントからMDXコメントへの移行 Migrate Markdown comments to MDX comments #545
  • Admonitionの文法の移行 Migrate admonition syntax to v3 version #548
• 設定ファイルのESMへの移行 Migrate to ESM config #550

[chvmvd]

#143 対策として今まではpタグを使っていたが、MDX v3だと正しくパースされず、pタグがネストされてしまう。

パース前

<p>
  <span>Hello</span>aaaa
</p>

パース後

<p><p><span>Hello</span>aaaa</p></p>

MDX v3によって #143 は解決するので、単にpタグを削除すればよい。

#541 で解決。

[chvmvd]

移行完了しました。

PrettierがMDX v3に対応していない（#549）ことで #542 #544 が発生してしまっており、とりあえずprettier-ignoreしました。これ以降は、#549 側で対応します。