バージョン: 3.5.2

Docusaurus v3へのアップグレード

このドキュメントは、Docusaurus v2からDocusaurus v3へサイトをアップグレードするのに役立ちます。

Docusaurus v3は、サイトの調整が必要となる破壊的な変更を含む、新しいメジャーバージョンです。このプロセスをガイドし、いくつかのオプションの推奨事項についても説明します。

これは完全な書き換えではなく、破壊的な変更は比較的簡単に処理できます。最もシンプルなサイトは、最終的にnpmの依存関係を更新するだけでアップグレードできます。

主な破壊的な変更は、MDX v1からMDX v3へのアップグレードです。詳細については、MDX v2とMDX v3のリリースノートを参照してください。MDXは、Markdownコンテンツをより厳密に、そして微妙な違いでコンパイルするようになります。

アップグレード前

アップグレードする前に、Docusaurus v3に向けてサイトを準備することをお勧めします。Docusaurus v2で段階的に処理できる変更があります。そうすることで、Docusaurus v3への最終的なアップグレードに必要な作業を減らすことができます。

複雑なサイトの場合は、ビジュアルリグレッションテストを設定することもお勧めします。これは、サイトの見た目が変わらないようにするための良い方法です。Docusaurus v3は主に依存関係をアップグレードするものであり、視覚的な変更が発生するとは予想されません。

注

Docusaurus v3.0.0のリリースノートを確認し、ここで言及されている各変更の背後にある追加の有用な情報と動機についてプルリクエストを参照してください。

依存関係のアップグレード

Docusaurus v3にアップグレードするには、コアDocusaurusの依存関係（@docusaurus/name）だけでなく、その他の関連パッケージもアップグレードする必要があります。

Docusaurus v3は、次の依存関係を使用するようになりました

Node.js v18.0+
React v18.0+
MDX v3.0+
TypeScript v5.1+
prism-react-renderer v2.0+
react-live v4.0+
remark-emoji v4.0+
mermaid v10.4+

コミュニティプラグインのアップグレード

サイトでサードパーティのコミュニティプラグインとテーマを使用している場合は、それらをアップグレードする必要がある場合があります。

アップグレードを試みる前に、これらのプラグインがDocusaurus v3と互換性があることを確認してください。

一般的なpackage.jsonの依存関係アップグレードの例

package.json
 {
   "dependencies": {
     // upgrade to Docusaurus v3
-    "@docusaurus/core": "2.4.3",
-    "@docusaurus/preset-classic": "2.4.3",
+    "@docusaurus/core": "3.0.0",
+    "@docusaurus/preset-classic": "3.0.0",
     // upgrade to MDX v3
-    "@mdx-js/react": "^1.6.22",
+    "@mdx-js/react": "^3.0.0",
     // upgrade to prism-react-renderer v2.0+
-    "prism-react-renderer": "^1.3.5",
+    "prism-react-renderer": "^2.1.0",
     // upgrade to React v18.0+
-    "react": "^17.0.2",
-    "react-dom": "^17.0.2"
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
   },
   "devDependencies": {
     // upgrade Docusaurus dev dependencies to v3
-    "@docusaurus/module-type-aliases": "2.4.3",
-    "@docusaurus/types": "2.4.3"
+    "@docusaurus/module-type-aliases": "3.0.0",
+    "@docusaurus/types": "3.0.0"
   }
   "engines": {
     // require Node.js 18.0+
-    "node": ">=16.14"
+    "node": ">=18.0"
   }
 }

TypeScriptユーザーの場合

package.json
 {
   "devDependencies": {
     // swap the external TypeScript config package for the new official one
-    "@tsconfig/docusaurus": "^1.0.7",
+    "@docusaurus/tsconfig": "3.0.0",
     // upgrade React types to v18.0+
-    "@types/react": "^17.0.69",
+    "@types/react": "^18.2.29",
     // upgrade TypeScript to v5.1+
-    "typescript": "~4.7.4"
+    "typescript": "~5.2.2"
   }
 }

MDXのアップグレード

MDXは、.mdおよび.mdxファイルをReactコンポーネントにコンパイルするDocusaurusの主要な依存関係です。

MDX v1からMDX v3への移行は、Docusaurus v3の採用における主な課題です。ほとんどの破壊的な変更はMDX v2からのものであり、MDX v3は比較的小さなリリースです。

Docusaurus v2で正常にコンパイルされたドキュメントの一部は、Docusaurus v3ではコンパイルに失敗する可能性があります。

問題のあるコンテンツを事前に見つける

サイトでnpx docusaurus-mdx-checkerを実行して、Docusaurus v3でコンパイルに失敗するファイルのリストを取得します。

このコマンドは、コンテンツを互換性のある状態にするために必要な作業量を推定するのにも適しています。この作業のほとんどは、Docusaurus v3に向けてコンテンツを準備することで、アップグレードの前に実行できることを覚えておいてください。

他のドキュメントも異なるレンダリングになる可能性があります。

ビジュアルリグレッションテストを使用する

すべてのページの目視確認が難しい大規模なサイトの場合は、ビジュアルリグレッションテストを設定することをお勧めします。

MDXのアップグレードには、MDX v2とMDX v3のリリースブログ記事に記載されているすべての破壊的な変更が伴います。ほとんどの破壊的な変更はMDX v2からのものであり、MDX v3は比較的小さなリリースです。MDX v2の移行ガイドには、MDXファイルを更新する方法に関するセクションがあり、これは特に私たちに関連します。また、一般的なMDXエラーメッセージの解釈に役立つMDXのトラブルシューティングページも必ずお読みください。

更新されたMDXとReactのドキュメントページも必ずお読みください。

MDXプレイグラウンドの使用

MDXプレイグラウンドは、あなたの新しい親友です。これにより、コンテンツがReactコンポーネントにコンパイルされる方法を理解し、コンパイルまたはレンダリングの問題を個別にトラブルシューティングできます。

DocusaurusのMDXプレイグラウンドオプションの設定

Docusaurus v2で使用されているものと同様のコンパイル動作を得るには、MDXプレイグラウンドで次のオプションをオンにしてください。

MDXを使用する
remark-gfmを使用する
remark-directiveを使用する

Screenshot of the MDX playground's options panel, with only the "Use MDX", "Use remark-gfm", and "Use remark-directive" options checked

2つのMDXプレイグラウンドを並べて使用すると、コンテンツの一部がv2でコンパイル方法が異なるか、コンパイルに失敗することにすぐに気づくでしょう。

コンテンツを将来にわたって安全にする

目標は、問題のあるコンテンツをリファクタリングして、MDXの両方のバージョンで正常に動作するようにすることです。このようにすることで、Docusaurus v3にアップグレードするときに、このコンテンツはすぐに使用できるようになります。

MDXチェッカーCLIの使用

問題のあるコンテンツを簡単に見つけることができるdocusaurus-mdx-checker CLIを提供しています。サイトでこのコマンドを実行して、MDX v3でコンパイルに失敗するファイルのリストを取得します。

npx docusaurus-mdx-checker

コンパイルの問題ごとに、CLIはファイルのパスと調べる行番号をログに記録します。

Screenshot of the terminal showing an example MDX checker CLI output, with a few error messages

ヒント

このCLIを使用して、コンテンツをMDX v3と互換性を持たせるために必要な作業量を推定します。

警告

このCLIはベストエフォートであり、コンパイルエラーのみを報告します。

エラーは発生しないものの、コンテンツの表示に影響を与える可能性のある微妙なコンパイルの変更は報告しません。これらの問題をキャッチするには、ビジュアルリグレッションテストの使用をお勧めします。

一般的なMDXの問題

Docusaurusは、MDXに伴うすべての変更を網羅的に文書化することはできません。それはMDX v2とMDX v3の移行ガイドの責任です。

しかし、いくつかのDocusaurusサイトをアップグレードすることで、ほとんどの問題は、ドキュメント化したいくつかのケースに帰着することがわかりました。

`{`の誤った使用

{ 文字は、JavaScript式を開くために使用されます。{expression}の中に有効な式ではないものを記述すると、MDXは失敗します。

example.md

The object shape looks like {username: string, age: number}

エラーメッセージ

acornで式を解析できませんでした: 式の後に予期しないコンテンツがあります

アップグレード方法

このエラーを修正するための利用可能なオプション

インラインコードを使用する: {username: string, age: number}
HTMLコードを使用する: {
エスケープする: \{

`<`の誤った使用

< 文字は、JSXタグを開くために使用されます。JSXが無効だと判断された場合、MDXは失敗します。

example.md
Use Android version <5

You can use a generic type like Array<T>

Follow the template "Road to <YOUR_MINOR_VERSION>"

エラーメッセージ

名前の前に予期しない文字5 (U+0035) があります。文字、$、または_などの名前を開始できる文字が必要です。

<T> (1:6-1:9) の終了タグは、paragraphの終了タグの不一致mdast-util-mdx-jsxの前に必要です。

<YOUR_MINOR_VERSION> (134:19-134:39) の終了タグは、paragraphの前に必要です。

アップグレード方法

このエラーを修正するための利用可能なオプション

インラインコードを使用する: Array<T>
HTMLコードを使用する: < または <
エスケープする: \<

GFM自動リンクの誤った使用

DocusaurusはGitHub Flavored Markdown (GFM)をサポートしていますが、<link>構文を使用した自動リンクはMDXではサポートされなくなりました。

example.md
<[email protected]>

<http://localhost:3000>

エラーメッセージ

名前の予期しない文字@ (U+0040)。文字、数字、$、または_などの名前文字が必要です。属性の前の空白。またはタグの終了(注: MDXでリンクを作成するには、[text](url)を使用します)

ローカル名の前に予期しない文字/ (U+002F)。文字、$、または_などの名前を開始できる文字が必要です。(注: MDXでリンクを作成するには、[text](url)を使用します)

アップグレード方法

通常のMarkdownリンクを使用するか、<と>を削除してください。MDXとGFMはすでにリテラルを自動リンクできます。

example.md
[email protected]
[[email protected]](mailto:[email protected])

http://localhost:3000
[http://localhost:3000](http://localhost:3000)

小文字のMDXComponentマッピング

カスタムのMDXComponentマッピングを提供するユーザーの場合、コンポーネントは「サンドボックス化」されました

h1のMDXComponentマッピングは、# hiに対してのみ使用され、<h1>hi</h1>に対しては使用されません。
小文字のカスタム要素名は、それぞれのMDXComponentコンポーネントに置き換えられなくなりました。

見た目の違い

MDXComponentコンポーネントマッピングが以前のように適用されず、カスタムコンポーネントが使用されなくなる可能性があります。

アップグレード方法

ネイティブのMarkdown要素の場合、小文字を引き続き使用できます: p, h1, img, a...

その他の要素には、大文字の名前を使用してください。

src/theme/MDXComponents.js
 import MDXComponents from '@theme-original/MDXComponents';

 export default {
   ...MDXComponents,
   p: (props) => <p {...props} className="my-paragraph"/>
-  myElement: (props) => <div {...props} className="my-class" />,
+  MyElement: (props) => <div {...props} className="my-class" />,
 };

意図しない余分な段落

MDX v3では、余分な改行を必要とせずに、JSXとMarkdownをより簡単にインターリーブできるようになりました。複数の行にコンテンツを記述すると、新しい予期された<p>タグが生成されることもあります。

見た目の違い

このコンテンツがMDX v1とv3でどのように異なるレンダリングされるかを確認してください。

example.md
<div>Some **Markdown** content</div>
<div>
  Some **Markdown** content
</div>

MDX v1の出力
<div>Some **Markdown** content</div>
<div>Some **Markdown** content</div>

MDX v3の出力
<div>Some <strong>Markdown</strong> content</div>
<div><p>Some <strong>Markdown</strong> content</p></div>

アップグレード方法

余分な<p>タグが必要ない場合は、ケースバイケースでコンテンツをリファクタリングして、単一行のJSXタグを使用します。

 <figure>
   <img src="/img/myImage.png" alt="My alt" />
-  <figcaption>
-    My image caption
-  </figcaption>
+  <figcaption>My image caption</figcaption>
 </figure>

また、まだMarkdown構文を使用する予定がない場合は、{と}でコンテンツをラップして、余分な<p>タグを回避することもできます。

-<figure>
+{<figure>
   <img src="/img/myImage.png" alt="My alt" />
   <figcaption>
     My image caption
   </figcaption>
-</figure>
+</figure>}

意図しないディレクティブの使用

Docusaurus v3では、アドモニション、および今後リリースされるDocusaurus機能をサポートするための一般的な方法として、Markdownディレクティブ(remark-directiveで実装) が使用されるようになりました。

example.md
This is a :textDirective

::leafDirective

:::containerDirective

Container directive content

:::

見た目の変更

ディレクティブは、他のRemarkプラグインで処理される目的で解析されます。未処理のディレクティブは無視され、元の形式でレンダリングされません。

example.md

The AWS re:Invent conf is great

:Inventがテキストディレクティブとして解析されるため、これは以下のようにレンダリングされます。

The AWS re
conf is great

アップグレード方法

HTMLコードを使用する: :
: の後にスペースを追加する (意味がある場合): : text
エスケープする: \:

サポートされていないインデントされたコードブロック

MDXは、インデントされたテキストをコードブロックとして変換しなくなりました。

example.md

    console.log("hello");

見た目の変更

アップグレードでは、通常、新しいMDXコンパイルエラーは発生しませんが、コードブロックがなくなったため、コンテンツが予期しない方法でレンダリングされる可能性があります。

アップグレード方法

インデントではなく、通常のコードブロック構文を使用します。

example.md
```js
console.log('hello');
```

その他のMarkdownの非互換性

スペースまたは句読点で始まる/終わる強調

新しいMDXパーサーは、CommonMark仕様に厳密に準拠するようになりました。CommonMark仕様では、特に単語を分割するためにスペースを使用しない言語との互換性のないスペースと句読点に関する強調のルールが、v0.14以降導入されています。

日本語と中国語が最も影響を受けていますが、一部の他の言語(例: タイ語とクメール語)にも影響を与える可能性があります。たとえば、インラインコードやリンクを強調しようとする場合です。単語を分割するためにスペースを使用する言語は、影響がはるかに少なくなります。

次の例の** (`**`以外) は、Docusaurus 2では意図したとおりに解析されましたが、Docusaurus 3では解析されなくなりました。

example.md
**Do not end a range of emphasis with a space. **Or `**` will not work as intended.

<!-- Japanese -->
**「。」の後に文を続けると`**`が意図した動作をしません。**また、**[リンク](https://docusaurus.dokyumento.jp/)**や**`コード`**のすぐ外側に`**`、そのさらに外側に句読点以外がある場合も同様です。

詳細な条件とアップグレード方法を参照してください

*または**が次のいずれかの条件に一致する場合、強調マークの先頭として機能しなくなります

次の文字がスペースである場合(例: word* word)
前の文字が句読点文字で、次の文字が文字である場合(スペースまたは句読点文字ではない)(例: 文**（文）)

反対に、*または**が次のいずれかの条件に一致する場合、強調マークの終わりとして機能しなくなります

前の文字がスペースである場合(例: word *word)
次の文字が句読点文字で、前の文字が文字である場合(例: 文。**文)

「句読点文字」には、非ASCII文字、括弧、引用符、および%や@を含むいくつかの記号が含まれます。より厳密に言えば、2文字のUnicodeカテゴリがPで始まる文字は、ここで句読点文字として扱われます。

アップグレード方法

問題のある強調マークがスペースの隣にある場合は、強調の範囲外にスペースを移動します

english.md
**Do not end a range of emphasis with a space.** Or `**` will not work.

問題のある強調マークが句読点文字と文字の両方で囲まれている場合は、コンテンツを変更せずに次の方法で修正できます。

もしドキュメントがプレーンなMarkdownである場合は、MDXに変換してください。
問題のある強調マークを生のHTMLタグ（<em> または <strong>）に置き換えてください。

japanese.mdx

<strong>「。」の後に文を続けると`**`が意図した動作をしません。</strong>また、<strong>[リンク](https://docusaurus.dokyumento.jp/)</strong>や<strong>`コード`</strong>のすぐ外側に`**`、そのさらに外側に句読点以外がある場合も同様です。

理想的な解決策ではありませんが、ドキュメントをMDXに変換せずに、以下のいずれかの方法も可能です。

最も外側の句読点を強調マークの外に移動してください。

japanese.md
**「。」の後に文を続けると`**`が意図した動作をしません**。また、[**リンク**](https://docusaurus.dokyumento.jp/)や・・・

問題のある*または**のすぐ外側にスペースを挿入してください。この解決策では、ドキュメントをMDXに変換する必要はありません。

japanese.md
**「。」の後に文を続けると`**`が意図した動作をしません。** また、**[リンク](https://docusaurus.dokyumento.jp/)** や **`コード`** のすぐ外側に`**`、そのさらに外側に句読点以外がある場合も同様です。

MDXプラグイン

MDXエコシステム内の公式パッケージ（Unified、Remark、Rehypeなど）はすべて、現在ES Modulesのみであり、CommonJSをサポートしなくなりました。

実際には、require("remark-plugin")のようなことはできなくなったということです。

アップグレード方法

Docusaurus v3は、現在ES Modules構成ファイルをサポートしています。設定ファイルをESモジュールに移行することをお勧めします。これにより、Remarkプラグインを簡単にインポートできるようになります。

docusaurus.config.js
import remarkPlugin from 'remark-plugin';

export default {
  title: 'Docusaurus',
  /* site config using remark plugins here */
};

CommonJSモジュールを使用し続けたい場合は、動的インポートを回避策として使用できます。これにより、CommonJSモジュール内でESモジュールをインポートできます。幸いなことに、Docusaurusの設定は、非同期関数の使用をサポートしているため、それが可能です。

docusaurus.config.js
module.exports = async function () {
  const myPlugin = (await import('remark-plugin')).default;
  return {
    // site config...
  };
};

プラグイン作者向け

カスタムのRemarkまたはRehypeプラグインを作成した場合、新しいASTの構造により、それらをリファクタリングするか、場合によっては完全に書き換える必要があるかもしれません。プラグイン作者がコードをアップグレードするのを支援するために、専用のサポートディスカッションを作成しました。

フォーマッター

最も一般的なフォーマッターであるPrettierは、Docusaurus v3.0.0の時点では、MDX v3ではなく、レガシーなMDX v1のみをサポートしています。コードの非互換部分の前に{/* prettier-ignore */}を追加すると、Prettierで動作させることができます。

{/* prettier-ignore */}
<SomeComponent>Some long text in the component</SomeComponent>

{/* prettier-ignore */}の挿入が多すぎることにうんざりした場合は、PrettierがMDX v3のサポートを開始するまで、.prettierignoreファイルに以下を追加して、PrettierによるMDXフォーマットを無効にすることを検討できます。

.prettierignore

*.mdx

その他の破壊的変更

MDX v3のアップグレード以外に、Docusaurus v3に伴う破壊的変更の包括的なリストを以下に示します。

Node.js v18.0

Node.js 16はサポート終了に達し、Docusaurus v3はNode.js >= 18.0を必要とするようになりました。

アップグレード方法

コンピュータにNode.js 18.0以降をインストールしてください。

必要に応じて、継続的インテグレーション、CDN、またはホストを構成して、この新しいNode.jsバージョンを使用するようにしてください。

また、サイトのpackage.jsonを更新して、サポートされていない古いバージョンの使用を防止できます。

package.json
 {
   "engines": {
-     "node": ">=16.14"
+     "node": ">=18.0"
   }
 }

Docusaurus v3にアップグレードする前に、Docusaurus v2サイトをNode.js 18にアップグレードしてください。

React v18.0+

Docusaurus v3は、現在React >= 18.0を必要とします。

React 18には、サイト用に作成したカスタムReactコードの量に応じて比較的簡単に処理できるはずの独自の破壊的変更が付属しています。公式のテーマとプラグインはReact 18と互換性があります。

アップグレード方法

公式のReact v18.0とReact 18へのアップグレード方法を読み、どのコンポーネントがこのアップグレードの影響を受ける可能性があるかを把握するために、独自のReactコードを確認してください。

特に以下に注意することをお勧めします。

ステートフルコンポーネントの自動バッチ処理
コンソールに報告される新しいReactハイドレーションエラー

React 18機能の実験的サポート

React 18には新機能が付属しています

<Suspense>
React.lazy()
startTransition

それらのDocusaurusサポートは実験的と見なされています。将来的には統合を調整する必要があり、実行時の動作が異なる可能性があります。

Prism-React-Renderer v2.0+

Docusaurus v3は、prism-react-rendererをv2.0以降にアップグレードします。このライブラリは、コードブロックの構文強調表示に使用されます。

アップグレード方法

これは、破壊的変更を含む新しいメジャーライブラリバージョンであり、厳密な後方互換性を保証することはできません。prism-react-renderer v2のリリースノートは完全ではありませんが、Docusaurusユーザーが認識しておくべき3つの主要な変更点があります。

依存関係をアップグレードする必要があります

package.json
 {
   "dependencies": {
-    "prism-react-renderer": "^1.3.5",
+    "prism-react-renderer": "^2.1.0",
 }

Docusaurus構成ファイルでテーマをインポートするためのAPIが更新されました

docusaurus.config.js
- const lightTheme = require('prism-react-renderer/themes/github');
- const darkTheme = require('prism-react-renderer/themes/dracula');
+ const {themes} = require('prism-react-renderer');
+ const lightTheme = themes.github;
+ const darkTheme = themes.dracula;

以前は、react-prism-render v1はデフォルトでより多くの言語を含めていました。v2.0以降では、デフォルトで含まれる言語が少なくなりました。Docusaurus構成に追加の言語を追加する必要がある場合があります

docusaurus.config.js
const siteConfig = {
  themeConfig: {
    prism: {
      additionalLanguages: ['bash', 'diff', 'json'],
    },
  },
};

React-Live v4.0+

@docusaurus/theme-live-codeblockパッケージのユーザー向けに、Docusaurus v3はreact-liveをv4.0以降にアップグレードします。

アップグレード方法

理論上は何もする必要はなく、既存のインタラクティブなコードブロックは以前と同じように動作し続けるはずです。

ただし、これは破壊的変更を含む新しいメジャーライブラリバージョンであり、厳密な後方互換性を保証することはできません。問題が発生した場合に備えて、v3とv4の変更ログをお読みください。

remark-emoji v4.0+

Docusaurus v3はremark-emojiをv4.0以降にアップグレードします。このライブラリは、Markdownでの:emoji:ショートカットをサポートするためのものです。

アップグレード方法

ほとんどのDocusaurusユーザーは何もする必要はありません。絵文字ショートコードのユーザーは、変更ログを読み、絵文字が期待どおりにレンダリングされ続けることを再確認する必要があります。

破壊的変更 node-emojiをv1からv2に更新します。この変更により、多くの新しい絵文字のサポートが導入され、GitHubで無効になった古い絵文字ショートコードが削除されました。

Mermaid v10.4+

@docusaurus/theme-mermaidパッケージのユーザー向けに、Docusaurus v3はmermaidをv10.4以降にアップグレードします。

アップグレード方法

理論上は何もする必要はなく、既存の図は以前と同じように動作し続けるはずです。

ただし、これは破壊的変更を含む新しいメジャーライブラリバージョンであり、厳密な後方互換性を保証することはできません。問題が発生した場合に備えて、v10の変更ログをお読みください。

TypeScript v5.1+

Docusaurus v3は、現在TypeScript >= 5.1を必要とします。

アップグレード方法

TypeScript 5+を使用するように依存関係をアップグレードしてください。

package.json
 {
   "devDependencies": {
-    "typescript": "~4.7.4"
+    "typescript": "~5.2.2"
   }
 }

TypeScript基本設定

公式のDocusaurus TypeScript構成は、外部パッケージ@tsconfig/docusaurusから、新しいモノレポパッケージ@docusaurus/tsconfigに内部化されました。

この新しいパッケージは、他のすべてのDocusaurusコアパッケージとともにバージョン管理され、主要バージョンアップグレードでのTypeScriptの後方互換性と破壊的変更を保証するために使用されます。

アップグレード方法

外部TypeScript構成パッケージを新しい公式パッケージに切り替えます。

package.json
 {
   "devDependencies": {
-    "@tsconfig/docusaurus": "^1.0.7",
+    "@docusaurus/tsconfig": "3.0.0",
   }
 }

tsconfig.jsonファイルで使用してください。

tsconfig.json
 {
-  "extends": "@tsconfig/docusaurus/tsconfig.json",
+  "extends": "@docusaurus/tsconfig",
   "compilerOptions": {
     "baseUrl": "."
   }
 }

新しい構成ローダー

Docusaurus v3は、内部構成ローディングライブラリをimport-freshからjitiに変更します。これは、docusaurus.config.jsやsidebars.jsなどのファイル、およびDocusaurusプラグインを読み込む役割を担います。

アップグレード方法

理論上は何もする必要はなく、既存の構成ファイルは以前と同じように動作し続けるはずです。

ただし、これは主要な依存関係のスワップであり、微妙な動作変更が発生する可能性があります。

注意喚起の警告

歴史的な理由から、ドキュメント化されていない :::warning という注意喚起をサポートしており、これは赤色で表示されます。

警告

これは Docusaurus v2 の :::warning 注意喚起です。

しかし、色とアイコンは常に間違っていました。Docusaurus v3 では :::warning 注意喚起が正式に再導入され、ドキュメント化され、色とアイコンが修正されました。

警告

これは Docusaurus v3 の :::warning 注意喚起です。

アップグレード方法

以前にドキュメント化されていない :::warning 注意喚起を使用していた場合は、各使用箇所で黄色が適切な色になっているか確認してください。赤い色を維持したい場合は、代わりに :::danger を使用してください。

Docusaurus v3 では、:::caution 注意喚起も非推奨になりました。:::caution（黄色）を :::warning（黄色）または :::danger（赤色）のいずれかにリファクタリングしてください。

「注意」というタイトルを維持したい場合は、:::warning[caution]（黄色）にリファクタリングすることをお勧めします。

バージョン管理されたサイドバー

この破壊的な変更は、v2.0.0-beta.10（2021年12月）より前にドキュメントをバージョン管理していた、Docusaurus v2 の初期採用者にのみ影響します。

バージョン v1.0.0 を作成するとき、サイドバーファイルには、Docusaurus v3 ではサポートされなくなったプレフィックス version-v1.0.0/ が含まれていました。

versioned_sidebars/version-v1.0.0-sidebars.json
{
  "version-v1.0.0/docs": [
    "version-v1.0.0/introduction",
    "version-v1.0.0/prerequisites"
  ]
}

アップグレード方法

バージョン管理されたサイドバーから不要なバージョン管理プレフィックスを削除してください。

versioned_sidebars/version-v1.0.0-sidebars.json
{
  "docs": ["introduction", "prerequisites"]
}

ブログフィードの制限

@docusaurus/plugin-content-blog は、デフォルトで RSS フィードを最新の 20 エントリに制限するようになりました。大規模な Docusaurus ブログの場合、これは RSS ファイルが肥大化するのを避けるためのより適切なデフォルト値です。

アップグレード方法

この新しいデフォルトの動作が気に入らない場合は、新しい limit: false フィードオプションを使用して、以前の「無制限フィード」の動作に戻すことができます。

docusaurus.config.js
const blogOptions = {
  feedOptions: {
    limit: false,
  },
};

ドキュメントテーマのリファクタリング

ドキュメント関連のテーマコンポーネント（@theme/DocPage など）をスウィズルしたユーザーの場合、これらのコンポーネントは、カスタマイズを容易にするために大幅にリファクタリングされています。

技術的には、これらのコンポーネントはスウィズルが安全ではないとフラグが立てられているため、これは破壊的な変更ではありません。ただし、多くの Docusaurus サイトがドキュメント関連のコンポーネントをエジェクトしており、カスタマイズによって Docusaurus が破損する可能性があることを知っておくと役立ちます。

アップグレード方法

スウィズルしたすべてのコンポーネントを削除し、再度スウィズルして、新しく更新されたコンポーネントの上にカスタマイズを再適用してください。

または、プルリクエストのメモを参照して、新しいテーマコンポーネントツリー構造を理解し、最終的にスウィズルしたコンポーネントを手動で修正することもできます。

オプションの変更

一部の変更は必須ではありませんが、Docusaurus v3 を最大限に活用するために知っておくと便利です。

自動 JSX ランタイム

Docusaurus v3 は、React 18 の「自動」JSX ランタイムを使用するようになりました。

React API を使用しない JSX ファイルでは、React をインポートする必要がなくなりました。

src/components/MyComponent.js
- import React from 'react';

  export default function MyComponent() {
    return <div>Hello</div>;
  }

ESM および TypeScript 構成

Docusaurus v3 は ESM および TypeScript 設定ファイルをサポートしており、これらの新しいオプションを採用することをお勧めします。

docusaurus.config.js
export default {
  title: 'Docusaurus',
  url: 'https://docusaurus.dokyumento.jp',
  // your site config ...
};

docusaurus.config.ts
import type {Config} from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';

const config: Config = {
  title: 'My Site',
  favicon: 'img/favicon.ico',
  presets: [
    [
      'classic',
      {
        /* Your preset config here */
      } satisfies Preset.Options,
    ],
  ],

  themeConfig: {
    /* Your theme config here */
  } satisfies Preset.ThemeConfig,
};

export default config;

`.mdx` 拡張子の使用

Markdown ファイル内で JSX、import、または export（つまり、MDX 機能）を使用する場合は、.mdx 拡張子を使用することをお勧めします。これは意味的により正確であり、外部ツール（IDE、フォーマッタ、リンターなど）との互換性が向上します。

Docusaurus の将来のバージョンでは、.md ファイルはこれらの機能をサポートしていない標準の CommonMark として解析されます。Docusaurus v3 では、.md ファイルは引き続き MDX ファイルとしてコンパイルされますが、CommonMark をオプトインできるようになります。

数式パッケージのアップグレード

Docusaurus を使用して数式をレンダリングする場合は、MDX プラグインをアップグレードする必要があります。

Docusaurus v3 (MDX v3 を使用) では、remark-math 6 と rehype-katex 7 を必ず使用してください。他のバージョンが動作することは保証できません。

{
-  "remark-math": "^3.0.0",
+  "remark-math": "^6.0.0",
-  "rehype-katex": "^5.0.0"
+  "rehype-katex": "^7.0.0"
}

hast-util-is-element は Docusaurus v3 では不要になりました。インストール済みで、他の場所で使用しない場合は、npm uninstall hast-util-is-element を実行して削除できます。

MDX v1 の互換性をオフにする

Docusaurus v3 には、デフォルトでオンになっている MDX v1 の互換性オプションが付属しています。

docusaurus.config.js
export default {
  markdown: {
    mdx1Compat: {
      comments: true,
      admonitions: true,
      headingIds: true,
    },
  },
};

`comments` オプション

このオプションを使用すると、HTML コメントは公式にはサポートされなくなりましたが、MDX 内で HTML コメントを使用できます。

MDX ファイルの場合、HTML  の代わりに、徐々に MDX {/* comments */} を使用し、この互換性オプションをオフにすることをお勧めします。

ブログの切り捨てマーカー

デフォルトのブログの切り捨てマーカーは、 と {/* truncate */} の両方をサポートするようになりました。

`admonitions` オプション

このオプションを使用すると、Docusaurus v2 の注意喚起タイトル構文を使用できます。

:::note Your Title

content

:::

Docusaurus は現在、Markdown Directives ( remark-directive で実装) を使用して注意喚起を実装しており、ディレクティブラベルを提供するための構文には角括弧が必要です。

:::note[Your Title]

content

:::

新しい Markdown ディレクティブラベル構文を徐々に使用し、この互換性オプションをオフにすることをお勧めします。

`headingIds` オプション

このオプションを使用すると、Docusaurus v2 の明示的な見出し ID 構文を使用できます。

### Hello World {#my-explicit-id}

この構文は現在無効な MDX であり、{ 文字をエスケープする必要があります: \{#my-explicit-id}。

MDX の新しいバージョンと互換性のある新しい構文を提供するまでは、この互換性オプションをオンにしておくことをお勧めします。

トラブルシューティング

アップグレードで問題が発生した場合、最初に試すべきことは次のとおりです。

MDX プレイグラウンド、または npx docusaurus-mdx-checker を使用して、すべてのドキュメントがコンパイルされていることを確認してください。
node_modules と package-lock.json を削除してから、再度 npm install を実行してください。
docusaurus clear を実行してキャッシュをクリアしてください。
Docusaurus v3 をサポートしていない可能性のあるサードパーティ製プラグインを削除してください。
スウィズルしたすべてのコンポーネントを削除してください。

試行錯誤したら、次のサポートチャネルを通じてサポートを依頼できます。

当社の時間は貴重です。サポートリクエストが無視されないようにするために、次のことをお願いいたします。

docusaurus.new で作成するのが理想的な、簡単に実行できる最小限の再現を提供してください。
問題が発生している様子を示すライブデプロイメント URL を提供してください（サイトをビルドできる場合）。
「動作しない」のような曖昧な表現ではなく、問題を明確に説明してください。
コードスニペット、リポジトリ URL、git ブランチ URL、完全なスタックトレース、スクリーンショット、ビデオなど、可能な限り関連性の高い資料を含めてください。
明確かつ簡潔にリクエストを提示し、当社がお客様を支援するために努力されたことを示してください。

または、有料の Docusaurus サービスプロバイダーにこのアップグレードの実行を依頼することもできます。サイトがオープンソースの場合は、コミュニティに無料の善意による支援を求めることもできます。

依存関係のアップグレード​

MDXのアップグレード​

MDXプレイグラウンドの使用​

MDXチェッカーCLIの使用​

一般的なMDXの問題​

{の誤った使用​

<の誤った使用​

GFM自動リンクの誤った使用​

小文字のMDXComponentマッピング​

意図しない余分な段落​

意図しないディレクティブの使用​

サポートされていないインデントされたコードブロック​

その他のMarkdownの非互換性​

スペースまたは句読点で始まる/終わる強調​

MDXプラグイン​

フォーマッター​

その他の破壊的変更​

Node.js v18.0​

React v18.0+​

Prism-React-Renderer v2.0+​

React-Live v4.0+​

remark-emoji v4.0+​

Mermaid v10.4+​

TypeScript v5.1+​

TypeScript基本設定​

新しい構成ローダー​

注意喚起の警告​

バージョン管理されたサイドバー​

ブログフィードの制限​

ドキュメントテーマのリファクタリング​

オプションの変更​

自動 JSX ランタイム​

ESM および TypeScript 構成​

.mdx 拡張子の使用​

数式パッケージのアップグレード​

MDX v1 の互換性をオフにする​

comments オプション​

admonitions オプション​

headingIds オプション​

トラブルシューティング​

依存関係のアップグレード

MDXのアップグレード

MDXプレイグラウンドの使用

MDXチェッカーCLIの使用

一般的なMDXの問題

`{`の誤った使用

`<`の誤った使用

GFM自動リンクの誤った使用

小文字のMDXComponentマッピング

意図しない余分な段落

意図しないディレクティブの使用

サポートされていないインデントされたコードブロック

その他のMarkdownの非互換性

スペースまたは句読点で始まる/終わる強調

MDXプラグイン

フォーマッター

その他の破壊的変更

Node.js v18.0

React v18.0+

Prism-React-Renderer v2.0+

React-Live v4.0+

remark-emoji v4.0+

Mermaid v10.4+

TypeScript v5.1+

TypeScript基本設定

新しい構成ローダー

注意喚起の警告

バージョン管理されたサイドバー

ブログフィードの制限

ドキュメントテーマのリファクタリング

オプションの変更

自動 JSX ランタイム

ESM および TypeScript 構成

`.mdx` 拡張子の使用

数式パッケージのアップグレード

MDX v1 の互換性をオフにする

`comments` オプション

`admonitions` オプション

`headingIds` オプション

トラブルシューティング