Docusaurus 2.0 の発表

本日、ついに Docusaurus 2.0 を発表できることを大変嬉しく思います！ 🥳️

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

4 年間の作業、75 個のアルファ版、22 個のベータ版を経て、Docusaurus の次世代版が実用段階に達しました。今後は、セマンティックバージョニングを尊重し、メジャーバージョンをより頻繁にリリースする予定です。

ProductHunt と Hacker News で紹介されています！

今こそ、Docusaurus への愛を示す絶好の機会です！

Docusaurus とは一体何ですか？​

Docusaurus は、美しいドキュメント Web サイトをすぐに公開するのに役立つ静的サイトジェネレーターです。

コンテンツに集中してください。Markdown ファイルを書くだけです。Docusaurus は、どこにでもホストできる最適化されたWeb サイトを生成します。

Docusaurus はフル機能で非常に柔軟です。洗練されたドキュメントとブログのレイアウト、すぐに使えるバージョン管理、検索、国際化機能が付属しており、アクセシビリティと検索エンジン最適化に配慮しています。柔軟なテーマ設定システムにより、UI をブランドに合わせて調整し、メイン Web サイトやドキュメントポータルにうまく統合できます。React の使用により、モダンなクライアントサイドナビゲーションと、インタラクティブなドキュメントを構築できます。

Docusaurus の理念は、パレートの法則に似ています。20% の労力で80% の成果を得ることができます。これにより、最小限の労力で一流のドキュメントサイトと競合することができます。

Docusaurus は最高のドキュメントツールを目指していますが、ブログ、ナレッジベース、開発者ポートフォリオ、セカンドブレイン、またはランディングページの足場としてなど、他のユースケースにも使用できます！

Docusaurus の背後にある物語​

Docusaurus は、2017 年に Facebook Open Source（現在は Meta Open Source）で作成されました。ドキュメント化する必要のある社内外のプロジェクトがたくさんありました。見栄えの良い Web サイト用の HTML、CSS、JavaScript を作成するのはもちろんのこと、適切なドキュメントを作成するのは十分に複雑です。プロジェクトリーダーがコンテンツに集中できるようにしたかったのですが、Markdown はそのために最適です。

当時、私たちのソリューションは、Jekyll テンプレートを何度もコピー/ペーストすることでした。これは当然保守が困難になったため、自分たちの問題を解決するためのツールを一度に作成しました。

Docusaurus v1 が誕生しました!

すぐに Facebook とフロントエンドエコシステムで勢いを増し、Prettier、Babel、React-Native、KaTeX、そしてもちろんDocusaurus v1自体など、多くの人気プロジェクトで採用されました。

Docusaurus 2.0 に向けて​

Docusaurus v1 は非常に成功しましたが、いくつかのアーキテクチャの選択について疑問を持ち始めました。

• React は、サーバーサイドのテンプレート言語としてのみ使用されており、クライアントでは使用されていませんでした
• テーマシステムはかなり制限されており、CSS でいくつかの色を変更する以外に、より高度なカスタマイズを行うことは困難でした
• ドキュメントのバージョン管理システムは、diff アルゴリズムに基づいていたため、混乱を招きました
• コードベースはモノリシックで、十分にテストされておらず、拡張も簡単ではありませんでした

Docusaurus v2 は、新しいモジュール式アーキテクチャで一から再構築されました

• React はクライアントでも使用されるようになり、モダンなシングルページアプリケーションナビゲーションが可能になりました
• プラグインにより、コミュニティはサードパーティパッケージとして便利な機能を提供できるようになります
• テーマはこれまで以上に柔軟になりました
• ドキュメントのバージョン管理は、理解しやすいスナップショットコピーに基づくようになりました
• ドキュメント、ブログ、ページ、バージョン管理、i18n など、v1 の良い点はすべて維持しました
• いくつかの新機能を実装しました

Docusaurus 2 プロジェクトの発表と v1 から v2 への移行ガイドで詳細をご確認ください

Docusaurus 2.0 を使用しているのは誰ですか？​

プレリリース中にもかかわらず、Docusaurus v2 は NPM ダウンロード数で Docusaurus v1 をすぐに上回りました

GitHub のスターの傾向は非常に肯定的で、主要なフレームワークと競合しています

現在、Docusaurus v2 は発売前にもかかわらず、すでに大成功を収めています

• 非常に多くの素晴らしい証言を受け取りました
• 1Password や Courier のような企業は、肯定的な経験を書き記しています
• 私たちのサイトショーケースには数百のサイトが掲載されており、これは氷山の一角にすぎません。

2.0の新機能​

Docusaurus v2で提供されるすべての新機能を説明することは難しいでしょう。ここでは、最も影響が大きいと私たちが信じている機能に焦点を当てましょう。

MDX​

MDXを使用すると、MarkdownにReactコンポーネントを挿入できます。これにより、非常に簡単に最高レベルのインタラクティブなドキュメントエクスペリエンスを構築できます。

デモは千の言葉に値します。

### Give it a try: press that button!

import ColorModeToggle from '@theme/ColorModeToggle';

<ColorModeToggle/>

ファイルシステム規則​

私たちの目標は、Docusaurusを非常に直感的に使用できるようにすることです。ファイルシステム規則を追加し、ドキュメントページを追加することは、1つのMarkdownファイルを作成するのと同じくらい簡単になりました。

プラグイン​

Docusaurusには、プラグインシステムを備えたモジュール式アーキテクチャが導入されました。ドキュメント、ブログ、ページ、検索などのコア機能はすべて、個別のプラグインによって駆動されます。

さらに重要なことは、コミュニティが追加機能でDocusaurusを強化できるようになったことです。

いくつかの例を挙げましょう。

• redocusaurus：OpenAPIおよびRedocとのシームレスな統合

• docusaurus-preset-shiki-twoslash：Shikiコードブロック構文ハイライトをTwoSlash TypeScriptコンパイラーヒントとともに使用

• docusaurus-search-local：組み込みのAlgoliaプラグインに対するさまざまなローカル検索の代替手段の1つ

テーマ​

テーマは、Docusaurusの最も重要な機能の1つです。私たちは、プロフェッショナルなドキュメントサイトは会社のブランドを尊重し、一貫したエクスペリエンスを作成する必要があると考えています。

Docusaurusのテーマは、複数のレベルで非常に柔軟性があります。

• CSS変数をカスタマイズして、色、フォントなどを調整します。
• 独自のCSSスタイルシートを提供します。
• 独自のテーマをゼロから実装します。
• デフォルトテーマで提供される任意のReactコンポーネントをオーバーライドします。これをスウィズリングと呼びます。

これにより、カスタマイズに少し時間を費やす意欲のあるユーザーは、他のサイトとは異なる外観のサイトを構築できます。

その他の機能​

Docusaurus 2には、非常に長い便利な機能のリストが付属しています。

• テーマ：ダークモード、より優れたUIとUX、柔軟なthemeConfigオプション...
• ドキュメントのバージョン管理：ワークフローに適応するための柔軟なプラグインオプション
• ドキュメントサイドバー：折りたたみ可能なカテゴリ、カテゴリインデックスページ...
• ブログ：複数の著者、著者マップ、アーカイブページ...
• Markdown：タブ、数式、ライブコードブロック、リンク、柔軟なフロントマター...
• 検索：新しいAlgolia DocSearch 3エクスペリエンスを使用します。
• アセット：画像やその他の種類のファイルを簡単に組み込むことができます。
• 国際化：構成オプション、デフォルトテーマの翻訳...
• アクセシビリティ：ariaラベル、色のコントラスト、コンテンツへのスキップ、キーボードナビゲーション、プログレッシブエンハンスメント...
• SEO：適切なデフォルト、カスタマイズが簡単、正規URL、ソーシャルカード、no-index、サイトマップ、マイクロデータ、hreflang...
• PWA：サイトにオフラインサポートを追加し、インストール可能にします。
• フェイルファスト：厳密な構成検証、壊れたリンクの検出、不適切な本番環境デプロイメントの防止
• 構成ファイル、プラグイン、カスタムページ、テーマ作成者に対するTypeScriptサポート
• プレイグラウンド：docusaurus.newを使用して、ブラウザからDocusaurusを簡単に評価できます。
• カナリアリリース：@canary npmタグを使用して、他の誰よりも早く今後のリリースを使用します。
• テスト：Docusaurusは十分にテストされており、機能をドッグフーディングして、それらが引き続き機能するようにします。

なぜ今2.0なのか？​

私たちの熱心なフォロワーの多くは、ベータ版がすでに成功し、本番環境で広く使用されていることを考えると、Docusaurus 2.0のリリースに4年かかったのはなぜかと疑問に思っています。

その理由は、セマンティックバージョニングを尊重することを目指しているからです。これは、破壊的な変更をリリースするたびにメジャーバージョン番号をインクリメントすることを意味します。

これには、いくつかの理由で重要です。

• パブリックAPIのみを使用している限り、簡単なマイナーバージョンアップグレードを保証します。
• フロントエンドエコシステムの規則に従います。
• 新しいメジャーバージョンは、破壊的な変更を徹底的に文書化する機会です。
• 新しいメジャー/マイナーバージョンは、ブログ記事を通じて新機能を伝達する機会です。

問題は、柔軟なテーマシステムが、そもそも破壊的な変更が何であるかを知ることが難しい、非常に暗黙的なAPIサーフェスを作成することです。高度にカスタマイズされたDocusaurusサイトは、内部APIを使用してカスタマイズを実現しているため、Docusaurusのアップグレードに苦労する場合があります。今後のコード変更をより安全に行うことができるように、テーマの大幅なリファクタリングと、パブリックAPIの明確な定義に時間を費やしました。最も一般的なサイトのカスタマイズで内部APIを使用する必要がないように、このパブリックテーマAPIを今後も拡張していきます。

次は何ですか？​

Docusaurus 3.0の作業は開始されており、この次のバージョンは数か月以内にリリースされます。 安定したチャネルでコミュニティにできるだけ早く利用できるようにするために、Docusaurus 2.xマイナーバージョンで後方互換性のある変更をバックポートします。

今後のDocusaurusのメジャーバージョンにおけるロードマップ上の機能の例

• MDX 2.0にアップグレード
• Markdownインフラの改善
• テーマとスウィズル機能の改善
• TailwindCSSテーマ
• テーマ：navbar、ドキュメントサイドバー、ブログサイドバー、フッターのカスタムアイテムタイプをサポート
• 動的なnavbar：navbarアイテムのアクティベーション戦略
• カスタムソーシャルカード
• CSS-in-JSのサポート
• Node.js ESモジュールの使用
• ビルド時間パフォーマンスの改善
• Docusaurusプラグインの拡張、CMS統合

感謝​

すべての貢献者に感謝の意を表します。以下の方々を含みます。

• Docusaurusコアチーム：Alexey Pyltsyn、Joshua Chen、Sébastien Lorber、Yangshun Tay、およびすべての以前のチームメンバー
• Docusaurus 1.0を作成し、Meta Open SourceでのDocusaurus 2.0プロジェクトをサポートしてくれたJoel Marcey
• Meta Open SourceでのDocusaurusのすべての次のバージョンの開発をサポートしてくれたPaul O’Shannessy
• 私たちの最もかわいいマスコットSlashを作成してくれたEric Nakagawa
• Docusaurus v2の初期作業に大きく貢献してくれたEndilie Yacop Sucipto
• サポートしてくれたClément Vannicatte、Kevin Granger、そしてAlgoliaチーム全体
• Discordでの貴重なコード貢献、ドキュメントの改善、質問への回答をしてくれたすべてのコミュニティメンバー

特に、Docusaurus 2.0の早期導入者の方々には、アルファ版、ベータ版、カナリア版を評価していただき、多くの貴重なフィードバックをいただきました。本当にありがとうございました。素晴らしい体験をしていただけたことを心から願っており、今後のDocusaurus 3.0のプレリリースについても引き続きフィードバックを提供していただけると幸いです。

Meta Open Sourceにおいて、Docusaurusは最も成功しているプロジェクトの1つです。皆様が作成する素晴らしいドキュメンテーションWebサイトを見るのが楽しみです！サイトショーケースに投稿することを忘れないでください！

さあ、想像力を自由に羽ばたかせてください 🤪！

— Slash

ProductHunt と Hacker News で紹介されています！

🙏 Docusaurusの使用経験をコミュニティと共有してください！