Docusaurus v3に向けてサイトを準備する

2023年9月29日 ·14分で読めます

Docusaurusメンテナー、This Week In React編集者

警告

このブログ記事は、Docusaurus v3 がベータ版だったときに書かれたものです。Docusaurus v3 の現在の安定版にアップグレードする場合は、依存関係のバージョンとアップグレード手順にいくつかの変更があることに注意する必要があります。最新の移行手順については、アップグレードガイドを参照してください。

Docusaurus v3は現在ベータ版であり、公式リリースは間近です。この新しいメジャーバージョンに向けてサイトを準備するのに最適な時期です。

Docusaurus v3にはいくつかの破壊的変更があり、その多くはDocusaurus v2で今日処理できます。事前にサイトを準備することで、段階的に行うことができ、v3へのアップグレードが容易になります。

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

この記事では、主にこの新しいMDXバージョンに向けてコンテンツを準備する方法に焦点を当て、今日処理できる他のいくつかの破壊的変更もリストします。

警告

この記事では、Docusaurus v3のほとんどの破壊的変更について言及していますが、網羅的ではありません。完全なリストについては、v3.0.0-beta.0のリリースノートをお読みください。

恐れないでください

このブログ記事には多くのコンテンツが含まれていますが、多くのDocusaurus v2サイトはごくわずかな変更でアップグレードできます。

カスタマイズが少ない、比較的小規模なサイトの場合は、おそらくすぐにDocusaurus v3にアップグレードできます。

準備作業

Docusaurus v3へのアップグレードの準備をする前に、最新のDocusaurus v2バージョンにアップグレードすることをお勧めします。

サイトの複雑さによっては、最近紹介したビジュアルリグレッションテストワークフローを採用するのが良い考えかもしれません。これは、Docusaurus v3へのアップグレード中に発生する予期しない視覚的な副作用をキャッチするのに役立ちます。

また、Markdownファイル内でJSX、import、またはexport（つまりMDX機能）を使用する場合は、.mdx拡張子を使用することをお勧めします。これは意味的により正しく、外部ツール（IDE、フォーマッター、リンターなど）との互換性が向上します。Docusaurusの今後のバージョンでは、.mdファイルはこれらの機能をサポートしていない標準のCommonMarkとして解析されます。Docusaurus v3では、.mdファイルは引き続きMDXファイルとしてコンパイルされますが、CommonMarkを選択することができます。

MDX v3のコンテンツの準備

MDXは、Docusaurusの主要な依存関係であり、.mdファイルと.mdxファイルをReactコンポーネントにコンパイルする役割を担っています。

MDX v3ははるかに優れていますが、おそらくコンテンツを少しリファクタリングする必要がある変更も含まれています。MDX v3はより厳格であり、v1では正常にコンパイルされた一部のコンポーネントが、{および<文字が原因で、v3ではコンパイルに失敗する可能性があります。

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

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

助けを求める

専用のMDX v3 - アップグレードサポートディスカッションがあります。

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

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

各MDXバージョンには独自のプレイグラウンドが付属しています

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プレイグラウンドを並べて使用すると、一部のコンテンツがv3でコンパイル方法が異なったり、コンパイルに失敗したりすることにすぐに気付くでしょう。

コンテンツを将来に対応させる

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

MDXチェッカーCLIの使用

問題のあるコンテンツを簡単に特定できるdocusaurus-mdx-checker CLIを提供しています。今日Docusaurus v2サイトでこのコマンドを実行して、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 サイトを Docusaurus v3 および MDX v3 にアップグレードしました。

これらのアップグレードにより、最も一般的なコンテンツの問題を集約し、それらに対応するための最良の方法を文書化することができました。

`{` の誤った使用

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

example.md

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

エラーメッセージ

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

準備方法

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

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

`<` の誤った使用

< 文字は、JSX タグを開始するために使用されます。MDX では、JSX が無効であると判断した場合、失敗するようになりました。

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) があります。文字、$、または _ など、名前を開始できる文字が必要です。

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

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

準備方法

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

インラインコードを使用する: Array<T>
HTML コードを使用する: < または <
エスケープする: \< (残念ながら \ は MDX v1 で表示されます)

GFM Autolink の誤った使用

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

example.md
<[email protected]>

<http://localhost:3000>

エラーメッセージ

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

ローカル名の前に予期しない文字 / (U+002F) があります。文字、$、または _ など、名前を開始できる文字が必要です (注: MDX でリンクを作成するには、[テキスト](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 では、追加の改行を必要とせずに、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> タグが不要な場合は、ケースバイケースでコンテンツをリファクタリングして、1 行の JSX タグを使用します。

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

コンテンツに「Markdown インライン」(**、*、_、[link](/path)) が含まれている場合は、事前にリファクタリングできない可能性があり、Docusaurus v3 へのアップグレードと並行して行う必要があります。

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

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 v1 で表示されます)

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

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

example.md

    console.log("hello");

見た目の変化

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

準備方法

インデントの代わりに、通常のコードブロック構文を使用します。

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

MDX プラグイン

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

実際には、require("remark-plugin") を実行できなくなったことを意味します。

準備方法

Docusaurus v3 は、現在 ES モジュール構成ファイルをサポートしています。構成ファイルを 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 の構造により、それらをリファクタリングするか、最終的には完全に書き直す必要がある場合があります。プラグイン作成者がコードをアップグレードするのを支援するために、専用のサポートディスカッションを作成しました。

その他の破壊的な変更

MDX とは別に、サイトを事前に準備できるその他の破壊的な変更があります。特に、重要な依存関係のメジャーバージョンアップグレードがあります。

Node.js 18.0

Node.js 16 はサポート終了となり、Docusaurus v3 では Node.js >= 18.0 が必要になりました。

準備方法

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

React 18.0

Docusaurus v3 では、React >= 18.0 が必要になりました。

React 18には、独自の破壊的変更が含まれていますが、サイト用に作成したカスタムReactコードの量によっては、比較的簡単に対応できるはずです。

スウィズリングせずに公式テーマコードのみを使用するシンプルなDocusaurusサイトでは、何もする必要はありません。

準備方法

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

特に次の点に注意することをお勧めします。

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

TypeScript 5.0

Docusaurus v3では、TypeScript >= 5.0が必須になりました。

準備方法

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

TypeScript基本設定

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

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

準備方法

新しいDocusaurus v3 TypeScript設定は、以前のDocusaurus v2 TypeScript設定とほぼ同じです。TypeScript 5にアップグレードした場合、v2サイトでDocusaurus v3設定を使用することは既に可能です。

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

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

注意喚起のアドモニション

歴史的な理由から、赤色でレンダリングされるドキュメント化されていないアドモニション:::warningをサポートしています。

警告

これはDocusaurus v2の:::warningアドモニションです。

ただし、色とアイコンは歴史的に誤っています。Docusaurus v3では、:::warningアドモニションが正式に再導入され、ドキュメント化され、色とアイコンが修正されました。

警告

これはDocusaurus v3の:::warningアドモニションです。

準備方法

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

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

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

この破壊的変更は、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"
  ]
}

準備方法

Docusaurus v2サイトは、2つのサイドバー形式を同様に処理できます。

バージョン管理されたサイドバーから不要なバージョン管理された接頭辞を削除できます。

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

Docusaurus v3を今すぐ試す

Docusaurus v3は現在ベータ版であり、React-Native、Jest、および私たちのウェブサイトですでに本番環境で使用されています。

この新しいDocusaurusバージョンは、堅牢で本番環境にデプロイする準備ができていると考えています。コミュニティの初期導入者からの肯定的なフィードバックを受け取った後、間もなく正式にリリースされる予定です。

アップグレードを試し、3.0.0-beta.0リリースディスカッションスレッドで問題を報告していただけると大変助かります。

ほとんどのサイトでは、アップグレードは簡単です。ここで説明したように、事前にサイトを準備していれば、次の依存関係をアップグレードするだけで十分です。

package.json
 {
   "dependencies": {
-    "@docusaurus/core": "2.4.3",
-    "@docusaurus/preset-classic": "2.4.3",
-    "@mdx-js/react": "^1.6.22",
+    "@docusaurus/core": "3.0.0-beta.0",
+    "@docusaurus/preset-classic": "3.0.0-beta.0",
+    "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^1.3.5",
-    "react": "^17.0.2",
-    "react-dom": "^17.0.2"
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.4.3"
+    "@docusaurus/module-type-aliases": "3.0.0-beta.0"
   }
 }

助けを求める

次のサポートチャネルを通じて、アップグレードを支援します。

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

結論

Docusaurus v3は試す準備ができており、まもなくリリースされます。この記事では、アップグレードに必要な主要な変更点について、すでに大まかなイメージをつかむことができるでしょう。

最初の3.0リリースでは、新しいエキサイティングな機能を実装するための依存関係とインフラストラクチャのアップグレードに焦点を当てています。また、最終リリースノートで詳細を説明するいくつかの便利な機能も含まれています。

準備作業​

MDX v3のコンテンツの準備​

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

MDXチェッカーCLIの使用​

MDX でよくある問題​

{ の誤った使用​

< の誤った使用​

GFM Autolink の誤った使用​

小文字の MDXComponent マッピング​

意図しない追加の段落​

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

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

MDX プラグイン​

その他の破壊的な変更​

Node.js 18.0​

React 18.0​

TypeScript 5.0​

TypeScript基本設定​

注意喚起のアドモニション​

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

Docusaurus v3を今すぐ試す​

助けを求める​

結論​

準備作業

MDX v3のコンテンツの準備

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

MDXチェッカーCLIの使用

MDX でよくある問題

`{` の誤った使用

`<` の誤った使用

GFM Autolink の誤った使用

小文字の MDXComponent マッピング

意図しない追加の段落

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

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

MDX プラグイン

その他の破壊的な変更

Node.js 18.0

React 18.0

TypeScript 5.0

TypeScript基本設定

注意喚起のアドモニション

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

Docusaurus v3を今すぐ試す

助けを求める

結論