Docusaurus 3.0 の発表

2023年10月31日 ·11分の読書

Docusaurusメンテナー、This Week In Reactエディター

本日、Docusaurus 3.0 の発表をいたします！🥳

Meta Open Source では、Docusaurus が最小限の労力で最高のドキュメント Web サイトを構築するのに役立ち、コンテンツの記述という本当に重要なことに集中できるようにすると信じています。

これは Docusaurus の新しいメジャーバージョンであり、新しくエキサイティングな機能とアップグレードされた依存関係が付属しています。

セマンティックバージョニングの原則に沿って、このリリースには、v3 アップグレードガイドで詳細にドキュメント化された破壊的変更が含まれています。破壊的変更は面倒な場合がありますが、実装を計画しているDocusaurus の新機能の基礎を築くために必要なものです。

当初はより頻繁なメジャーバージョンのリリースを計画していましたが、Docusaurus v3 は予想よりも時間がかかりました。蓄積した破壊的変更の中で、MDX v3 へのアップグレードはおそらくこの新バージョンの採用における主な課題です。特にMDX v1 の互換性オプションを追加することにより、このアップグレードを可能な限り簡単にするために全力を尽くしました。

最もシンプルなサイトでは、いくつかの npm 依存関係をアップグレードするだけで済みます。より複雑なサイトの場合、より自信を持ってアップグレードするのに役立ついくつかの戦略を思いつきました。

Docusaurus v2 に留まりながら、事前にサイトを準備し、段階的に行います
アップグレード中に発生する予期しない視覚的な変化をキャッチするために、視覚的リグレッションテストを設定します。

Docusaurus v2 について

当社のリリースプロセスによると、Docusaurus v2 は現在、メンテナンスモードに入っています。2024 年 1 月 31 日まで、3 か月間、主要なセキュリティ問題のサポートのみを受けられます。その期間内に v3 にアップグレードすることをお勧めします。

破壊的変更

このセクションでは、概要を簡単に説明します。すべての破壊的変更は、v3 アップグレードガイドで詳細にドキュメント化されています。

Docusaurus v3 では、いくつかの依存関係が新しいメジャーバージョンにアップグレードされました。それぞれの依存関係には独自の破壊的変更が伴います。

Node.js v16 ➡️ v18
React v17 ➡️ v18
MDX v1 ➡️ v3
TypeScript v4 ➡️ v5
prism-react-renderer v1 ➡️ v2
react-live v2 ➡️ v4
Mermaid v9 ➡️ v10
import-fresh v3 ➡️ jiti v1
remark-emoji v2 ➡️ v4

一般的な 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"
   }
 }

MDX v3 を除いて、これらのアップグレードされた依存関係に伴うほとんどの破壊的変更は、内部的に処理されています。ほとんどの場合、何もする必要はありません。依存関係以外で、Docusaurus コードベースから明示的に発生する機能的な破壊的変更は、次のとおりです。

#9189: ブログ RSS フィードのデフォルト制限を 20 エントリに変更
#9308: :::warning 注意を修正して再導入し、:::caution を非推奨化
#9310: v2.0.0-beta.10 (2021 年 12 月) より前にバージョン管理されたサイトで使用される、従来のバージョン管理されたサイドバー ID プレフィックスを削除
#7966: ドキュメントのテーマコンポーネントをリファクタリングし、最終的にそれらを再スワズルする必要がある

ハイライト

以下は、この新バージョンに付属する新しい便利な機能の包括的ではないリストです。すべての機能は、Docusaurus v3.0.0 リリースノートに記載されています。

マークダウン

Docusaurus v3 では、MDX v1 から MDX v3 にアップグレードされました。

#8288 では、MDX v2 にアップグレードしました (移行ガイド)
#9451 では、MDX v3 にアップグレードしました (移行ガイド)

この新しい MDX バージョンは、コンテンツライターとプラグイン作成者にとってはるかに優れており、新しいエキサイティングなマークダウン機能を実装するための基礎となります。

MDX v3 - 主な課題

MDX v1 から MDX v3 への移行は、Docusaurus v3 の採用における主な課題です。

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

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

怖がらないでください。ほとんどの問題は簡単に修正でき、多くの場合、エスケープする必要がある { および < 文字に関連しています。ただし、サイトのサイズによっては、多くのファイルを編集する必要があり、圧倒されるかもしれません。このため、npx docusaurus-mdx-checker コマンドを提供して、実行される作業の見積もりを支援し、サイトを事前に準備することをお勧めします。

カスタム MDX プラグイン (Remark/Rehype) を作成した場合、AST はわずかに異なり、それらをリファクタリングする必要がある場合があります。

これにより、既存のドキュメントが Docusaurus を採用しやすくするためのCommonMark モードを追加できるようになります。これは現在、オプトインで実験的であり、制限されています (一部の Docusaurus 機能は動作しません)。Docusaurus v3 では、すべてのファイルは依然として MDX として解釈されますが、今後のメジャーバージョンでは .md ファイルを CommonMark として解釈し、JSX または ES モジュールを使用するファイルには .mdx 拡張子を使用することをお勧めします。

また、サイトのマークダウンをグローバルに設定する新しい方法も導入し、後でより柔軟なオプションを追加する予定です。

docusaurus.config.js
export default {
  markdown: {
    format: 'mdx',
    mermaid: true,
    preprocessor: ({filePath, fileContent}) => {
      return fileContent.replaceAll('{{MY_VAR}}', 'MY_VALUE');
    },
    mdx1Compat: {
      comments: true,
      admonitions: true,
      headingIds: true,
    },
  },
};

Docusaurus は、アドモニションをサポートするために remark-directive プラグインを使用するようになりました。これにより、:textDirective、::leafDirective、:::containerDirective などの独自のカスタムディレクティブを使用してマークダウンを拡張する独自の Remark プラグインを作成することもできます。

ESM および TypeScript 構成

#9317 では、サイト構成、ドキュメントサイドバー、プラグイン、プリセットなど、ESモジュールとTypeScriptの構成ファイルのサポートを追加しました。

以下に、IDE のオートコンプリートを使用したモダンなエクスペリエンスを提供する 2 つの TypeScript の例を示します。

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',
  // your site config ...
  presets: [
    [
      'classic',
      {
        // your preset config ...
      } satisfies Preset.Options,
    ],
  ],
  themeConfig: {
    // your theme config ...
  } satisfies Preset.ThemeConfig,
};

export default config;

sidebars.ts
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';

const sidebars: SidebarsConfig = {
  docs: ['introduction'],
};

export default sidebars;

リストにないコンテンツ

Docusaurus は、すでに 3 つのコンテンツプラグイン (ドキュメント、ブログ、ページ) で draft: true フロントマターオプションをサポートしており、これにより、本番ビルドから一部のページを削除できます。

#8004 では、新しい unlisted: true フロントマターオプションを導入しました。これにより、URL がない限り、ページを「非表示」にし、発見できなくしながら、ページを本番ビルドで使用可能な状態に保ちます。これにより、最終公開前にコンテンツに関するフィードバックを簡単に求めることができる便利なワークフローが可能になります。

リストにないコンテンツは、

sitemap.xml から除外されます
<meta name="robots" content="noindex, nofollow" /> のおかげで SEO 結果から除外されます
ブログ RSS フィードから除外されます
Algolia DocSearch の結果から除外されます
サイトのナビバー項目、ドキュメントサイドバー、ブログサイドバー、ブログアーカイブ、タグページなどからフィルタリングされます

また、リストにないコンテンツには、コンテンツの準備が整ったらオフにすることを忘れないように、バナーが表示されます。ここに、リストにないブログ投稿の例を示します。

/tests/blog/unlisted-post

React 18

#8961 では、React 18 にアップグレードしました。これは、同時実行 React 機能の段階的な採用、およびビルド時の React サーバーコンポーネントなど、今後登場するエキサイティングな機能にとって特に重要です。

この新しいバージョンの React は、ほとんどの Docusaurus サイトでそのまま置き換えられるはずです。Docusaurus のコードベース内で内部的に処理した破壊的な変更が含まれています。もしあなたのサイトが多くのカスタム React コードを使用している場合は、React 18 へのアップグレード方法に関する公式記事、特に新しい自動バッチ処理の動作を確認することをお勧めします。

React 18 の機能の試験的なサポート

React 18 には新機能が搭載されています。

<Suspense>
React.lazy()
startTransition()

これらの Docusaurus でのサポートは実験的とみなされています。将来的に統合を調整する必要があるかもしれず、ランタイムの動作が異なる可能性があります。

自動 JSX ランタイム

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

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

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

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

デバッグビルド

開発モードで静的サイトをビルドできるようになりました。

docusaurus build --dev

React 関連の問題のデバッグ

Docusaurus は、新しいonRecoverableError コールバックを通じて、React 18 のハイドレーションエラーをはじめ、より多くのエラーをコンソールに出力します。

この新しいビルドモードは、特にReact の問題のトラブルシューティングに役立ちます。Docusaurus は React の開発ビルドを使用するため、React エラーデコーダーページにリンクされた縮小版のエラーメッセージではなく、詳細で読みやすいエラーメッセージを生成します。

TypeScript

Docusaurus v3 では、TypeScript の最小バージョンが 5.0 になりました。

ベースの推奨 TypeScript 設定を新しい公式パッケージに再内部化しました。

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

また、Docusaurus のコアタイプ、プラグイン、プリセットオプションのために、よりクリーンで正規化されたエクスポートがあり、新しく導入されたTypeScript 設定ファイル内で使用できます。

docusaurus.config.ts
import type {Config} from '@docusaurus/types';
import type {Options, ThemeConfig} from '@docusaurus/preset-classic';
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';

コードブロック

#9316では、prism-react-renderer v2 へのアップグレードのおかげで、構文のハイライトが改善されました。たとえば、bash パラメータ --save が色分けされるようになりました。

npm install --save some-package

インタラクティブなコードエディターも、新しいsucraseコンパイラを備えたreact-live v4 にアップグレードしました。高速で軽量であり、特に TypeScript の型注釈など、最新の機能をサポートしています。

ライブエディター

function Hello() {
  const name: string = 'World';
  return <div>Hello {name}</div>;
}

結果

読み込み中...

#8982と#8870では、TeX ライク、Haskell ライク、WebAssembly コメント構文のマジックコメントのサポートも追加しました。

haskell.hs
stringLength :: String -> Int
stringLength [] = 0
stringLength (x:xs) = 1 + stringLength xs

matlab.m
function result = times2(n)
  result = n * 2;
end
x = 10;
y = times2(x);

Mermaid ダイアグラム

#9305では、Mermaid v10.4 にアップグレードし、非同期ダイアグラムレンダリングのサポートを追加しました。Docusaurus は新しいタイプのダイアグラムをレンダリングできるようになりました。

マインドマップ

四分円チャート

クエリ文字列データ属性

#9028では、docusaurus-data-x クエリ文字列パラメータを介して、カスタム HTML データ属性を設定できるようになりました。これにより、Docusaurus iframe を別のサイトに埋め込みやすくなり、CSS を使用して埋め込まれたバージョンの外観をカスタマイズできます。

/src/css/custom.css
html[data-navbar='false'] .navbar {
  display: none;
}

html[data-red-border] div#__docusaurus {
  border: red solid thick;
}

/docs/?docusaurus-data-navbar=false&docusaurus-data-red-border

その他の機能

言及する価値のあるその他の新機能

#9189: 新しいブログの feedOptions.limit オプション
#9071: ページプラグインの正規化された SEO フロントマターサポートの追加
#9171: client-redirects プラグインで、完全に修飾された URL と、宛先 URL のクエリ文字列/ハッシュがサポートされるようになりました
#9171: 新しい ESLint ルール no-html-links
#8384: 新しい ESLint ルール prefer-docusaurus-heading

変更点の詳細については、Docusaurus v3.0.0 リリースノートをご覧ください。

結論

このリリースにはいくつかの機能が付属していますが、より重要なことに、Docusaurus インフラストラクチャの多くの部分がアップグレードされています。

MDX のアップグレードは今年多くの時間を費やしましたが、この重要なアップグレードを皆さんにとってより困難なものでないように努力しました。

インフラストラクチャに追いついたので、今後、役に立つドキュメント機能をマイナーバージョンですぐに提供する予定です。

長年にわたり Docusaurus をご利用いただきありがとうございます。ドキュメントフレームワークの分野は最近競争が激しくなってきており、Docusaurus がその優れた柔軟性で際立つ競争力のあるソリューションであり続けるよう、最善を尽くします。

破壊的変更​

ハイライト​

マークダウン​

ESM および TypeScript 構成​

リストにないコンテンツ​

React 18​

自動 JSX ランタイム​

デバッグビルド​

TypeScript​

コードブロック​

Mermaid ダイアグラム​

クエリ文字列データ属性​

その他の機能​

結論​