メインコンテンツにスキップ

Docusaurus 2を目指して

·10分
Endilie Yacop Sucipto
Endilie Yacop Sucipto
Docusaurusメンテナー

Docusaurusは、オープンソースのドキュメントウェブサイトを簡単に構築する方法として、9か月以上前に正式に発表されました。それ以来、8,600以上のGitHubスターを獲得し、React Native、Babel、Jest、Reason、Prettierなど、多くの人気のあるオープンソースプロジェクトで使用されています。

最高のソフトウェアは常に進化し、最悪のソフトウェアは進化しないという格言があります。ご存知ない方もいらっしゃるかもしれませんが、私たちはDocusaurusの次期バージョンを計画し、取り組んできました🎉。

はじめに​

すべては、2018年6月末にYangshunによって開設されたこのRFC issueから始まりました。

[RFC] Docusaurus v2 · Issue #789 · facebook/docusaurus

これらは、私が現在Docusaurusで見ている問題点と、v2でそれらに対処する方法です。ここでのアイデアの多くは、VuePressやその他の静的サイトジェネレーターに触発されています。現在の静的サイトジェネレーターのエコシステムでは、...

提案された改善点のほとんどはissueに記載されています。Docusaurus 1の問題点と、Docusaurus 2でそれらにどのように対処するかについて詳しく説明します。

インフラストラクチャ​

コンテンツ​

Docusaurus 1のウェブサイトは、実際には一連の静的HTMLページに組み込まれています。Reactを使用しているにもかかわらず、動的でインタラクティブなページを可能にするコンポーネントの状態など、Reactが提供する機能を sepenuhnya 活用していませんでした。Reactは静的コンテンツのテンプレートエンジンとしてのみ使用され、インタラクティビティはスクリプトタグとdangerouslySetInnerHTML😱を介して追加する必要がありました。

さらに、Docusaurusがコンテンツを読み込む方法を変更する簡単な方法はありませんでした。たとえば、SassやLessなどのCSSプリプロセッサはネイティブでサポートされておらず、カスタムスクリプトを追加する多くのユーザーハックが必要でした。

Docusaurus 2では、webpackをモジュールバンドラーとして使用し、コンテンツを提供する方法を変更します。CSSプリプロセッサの追加は、webpackローダーを追加するのと同じくらい簡単になります。純粋な静的HTMLの代わりに、**ビルド時にアプリのサーバーレンダリングバージョンを作成し**、対応するHTMLをレンダリングします。Docusaurusサイトは本質的にアイソモーフィック/ユニバーサルアプリケーションになります。このアプローチは、Gatsbyに大きく影響を受けています。

バージョン管理​

しばらくDocusaurusを使用している場合、ドキュメントのコンテンツが**異なる**場合**にのみ**、Docusaurusはバージョン管理されたドキュメントを作成することに気付くかもしれません。

たとえば、docs/hello.mdがあるとします

---
id: hello
title: hello
---
Hello world !

そして**バージョン1.0.0をカットすると、** Docusaurusはversioned_docs/version-1.0.0/hello.mdを作成します

---
id: version-1.0.0-hello
title: hello
original_id: hello
---
Hello world !

ただし、v2.0.0をカットするときにhello.mdに変更がない場合、Docusaurusはそのドキュメントのバージョン管理されたドキュメントを作成しません。つまり、versioned_docs/version-2.0.0/hello.mdは存在しません。

これはユーザーにとって非常に混乱を招く可能性があります。v2.0.0ドキュメントを編集したい場合、versioned_docs/version-1.0.0/hello.mdを編集するか、手動でversioned_docs/version-2.0.0/hello.mdを追加する必要があります。これは、予期しないバグにつながる可能性があります。Jestの実際のシナリオはこちらです。

さらに、バージョンのフォールバックメカニズムが必要になるため、コードベースの複雑さが増します。また、ビルド時に、Docusaurusは正しいバージョンへのリンクを置き換える必要があります。これは、ドキュメントの名前変更が古いバージョンのリンクを壊すバグの原因でもあります。

Docusaurus 2では、**新しいバージョンをカットするたびに、すべてのドキュメントのスナップショットを取得します**。ドキュメントの内容が変更されている必要はありません。これは、開発者とユーザーエクスペリエンスを向上させるための空間計算量のトレードオフです。懸念事項のより良い分離と正確性の保証のために、より多くのスペースを使用します。

翻訳​

Docusaurusは、Crowdinを使用して簡単に翻訳機能を提供します。英語で書かれたドキュメントファイルは、コミュニティ内のユーザーによる翻訳のためにCrowdinにアップロードされます。私たちは常に**英語**がデフォルト言語であると想定していましたが、これはすべてのユーザーに当てはまるとは限りません。Docusaurusを使用している英語以外のオープンソースプロジェクトはたくさんあります。

Docusaurus 2では、**英語がデフォルト言語であるとは想定しません**。ユーザーが国際化を有効にすると、siteConfig.jsでデフォルト言語を設定する必要があります。その後、docs内のすべてのファイルがその言語で書かれていると想定します。

さらに、Docusaurus 2のMVPに取り組んだ後、翻訳にCrowdinを使用しないことも可能であることに気付きました。したがって、そのシナリオを有効にするために追加のワークフローを追加する必要があるかもしれません。ただし、統合を容易にするために、Crowdinを使用することを強くお勧めします。

カスタマイズ性​

レイアウト​

Docusaurusの現在の状態は、レイアウトとスタイリング全体を担当しているため、ユーザーがサイトの外観を自分の希望どおりにカスタマイズすることが非常に困難になっています。

Docusaurus 2では、**レイアウトとスタイリングはユーザーが制御する必要があります**。Docusaurusは、コンテンツの生成、ルーティング、翻訳、およびバージョン管理を処理します。create-react-appとVuePressに触発されて、Docusaurusはデフォルトのテーマを提供しますが、ユーザーはそれをイジェクトして、レイアウトとスタイリングをさらにカスタマイズできます。これは、ユーザーがReact Helmetを使用してHTMLメタを変更することさえ可能であることを意味します。コミュニティベースのテーマも非常に可能です。ユーザーがレイアウトとスタイリングを担当できるようにするというこのアプローチは、ほとんどの静的サイトジェネレーターで採用されています。

Markdown​

Markdownの解析は現在、Remarkableによって提供されています。ユーザーがMarkdown-itまたはMDXを使用したい場合はどうでしょうか？そして、どの構文ハイライターを使用するかという問題があります（例：PrismとHighlight.js）。これらの選択肢はユーザーに任せるべきです。

Docusaurus 2では、**ユーザーはイジェクトして独自のMarkdownパーサーを選択できます**。Remarkなどの別のMarkdownパーサー、または独自の社内Markdownパーサーを使用する場合でも問題ありません。原則として、ユーザーはReactコンポーネントを提供する必要があり、そのコンポーネントには、*MarkdownのRAW文字列*を含むchildren propsを提供します。デフォルトでは、MarkdownパーサーにはRemarkableを、構文の強調表示にはHighlight.jsを使用します。デフォルトのパーサーは、さまざまなMarkdownパーサーをまだ試しているため、将来的に変更される可能性があります。

私たちのコア検索機能は、Algoliaに基づいています。オフライン検索用のlunrjsなど、異なる検索オファリングを使用できるようにしたいというユーザーからのリクエストがあります。

私は個人的にAlgoliaが好きで、彼らと協力した素晴らしい経験があります。彼らは非常に反応がよく、彼らのDocSearchはオープンソースであるため、Algoliaにプルリクエストを簡単に送信できます。たとえば、最近、サイトマップの代替言語をDocSearchがスクレイピングできるようにするこのPRを送信しました。

Docusaurus 2では、**ユーザーが検索ボックスをカスタマイズできるようにします**。ユーザーはデフォルトのテーマからイジェクトして、検索UI（Reactコンポーネント）を変更するだけです。ただし、デフォルトのテーマでは引き続きAlgoliaを使用します。

安定性​

ソフトウェアは決して完璧になることはありませんが、新しい機能を追加してもDocusaurusが壊れないようにしたいと考えています。Docusaurusが最初にリリースされたとき、強力な自動テストスイートはありませんでした。その結果、初期に捕捉されなかった多くのリグレッションがありました。最近多くのテストを追加しましたが、テストカバレッジはまだ比較的低いです。

Docusaurus 2では、新しい書き直しを目指しているため、**開発中にテストを追加しています**。したがって、Docusaurus 1よりも安定しており、壊れにくいと信じています。

よくある質問​

破壊的な変更はありますか？​

ここまで読んだ方は、破壊的な変更があることに気付くはずです。破壊的な変更の数を最小限に抑え、可能な限り後方互換性を維持するよう努めますが、いくつかの破壊的な変更は避けられないと考えています。これは主に、Docusaurus 2 がコードベースの大幅な書き換えと再設計であるためです。

開発が100%完了していないため、破壊的な変更の正確なリストはまだ完全には分かっていません。しかし、一つ強調しておきたいのは、siteConfig.js の多くのオプションを廃止し、可能な限り簡素化していく予定です。例えば、cleanUrl siteConfig は廃止されます。Docusaurus 2 サイトのすべての URL は .html 拡張子が付かないようになるためです。

私たちの目標は、ほとんどのサイトが大きな苦労なく Docusaurus 2 にアップグレードできるようにすることです。Docusaurus 2 のリリース時には、移行ガイドも提供する予定です。その時が来たら、Discord または Twitter でお気軽にご質問ください。

Docusaurus 2はいつリリースされますか？​

現時点では、リリースの正確な日付は決まっていません。個人的には、今後1～2ヶ月以内にアルファ版をリリースできる可能性があると推定していますが、これはもちろん、あくまでも推定です。

Docusaurus は Facebook Open Source の一部であり、チームのほとんどは Facebook の従業員ですが、メンテナンスと開発作業は主に通常の勤務時間外に行われています。私は現在、NTU シンガポール の最終学年の学部生であるため、授業、卒業プロジェクト、そして Docusaurus のメンテナンス/開発を両立させなければなりませんでした。しかし、だからといって Docusaurus をより良くしたいと思っていないわけではありません。実際、私たちは可能な限り素晴らしいものにしたいと思っています。

今のところ、実際の Docusaurus 2 の作業はまだプライベートリポジトリでホストされています。近い将来、パブリックリポジトリに移動する予定です。その時が来たら、ぜひ皆さんに見ていただき、できれば何らかの形で貢献していただければと思います。それまでは、どうぞお楽しみに 😉！

最後に​

ドキュメントに Docusaurus を使用している多くの人気プロジェクトから分かるように、Docusaurus はオープンソースコミュニティに大きな影響を与えてきました。今後、より迅速に進歩するために、Docusaurus 1 のいくつかのコアとなる問題を修正し、すべての人にとってより良い Docusaurus を目指しています。実際、Docusaurus 2 はもはや計画段階ではなく、作業が開始されており、近い将来に実現することを期待できると言っても過言ではありません。

Docusaurus の使命は、ドキュメント付きのウェブサイトをすぐに簡単に立ち上げられるようにすることです。この使命は、Docusaurus 2 でも変わりません。

また、Docusaurus 2 の作業のため、Docusaurus 1 での新機能/主要な変更の受け入れは少なくなることをお知らせしておきます。

Docusaurus を使用している方は、私たちのコミュニティの一員です。Docusaurus をどのように改善できるか、ご意見をお寄せください。私たちの活動に賛同していただける場合は、Open Collective で Docusaurus をサポートしてください。

Open Collective で私たちの活動を支援してくださっている方には、Docusaurus ウェブサイトのメンテナンスとアップグレードについて個別にサポートを提供します。

最後に、まだの方は、GitHub で **スター** と **ウォッチ** ボタンをクリックし、Twitter でフォローしてください。