ScalarDB および ScalarDL ドキュメント サイトを Jekyll から Docusaurus に移行する
この内容は機械翻訳されたものです。
2023 年半ばに、ScalarDB と ScalarDL のドキュメント サイトを立ち上げました。 実際、以前にこれらのドキュメント サイトの立ち上げに関する記事を書いたことを覚えているかもしれません。 ドキュメントを検索可能でナビゲート可能な方法で利用できるようにすることは、ユーザーが製品の使用方法を学習できるようにする上で大きな前進でした。
しかし、サイトとその維持に関連する内部プロセスが複雑になるにつれて、よりスケーラブルで機能が豊富な静的サイト ジェネレーターに移行する必要がありました。他のソリューションを調査した後、Docusaurus を選択しました。
このブログ投稿では、Jekyll から Docusaurus に移行した理由、実行した手順、移行後に観察された利点について説明します。
なぜ Jekyll から Docusaurus に移行したのでしょうか?
私たちは当初、Jekyll が当時最も成熟した静的サイト ジェネレーターだと考えていたため、Jekyll でドキュメント サイトを構築することを選択しました。 Jekyll と使用していたテーマは当初はうまく機能しましたが、最終的にはいくつかの制限があることに気づきました。
- カスタマイズの複雑さ: 進化するニーズに合わせて Jekyll テーマをカスタマイズすることは、ますます複雑になり、時間がかかるようになりました。 特に、折りたたみ可能なサイドバー ナビゲーションを実装する必要がありましたが、これには、使用していた Jekyll テーマの大幅なカスタマイズが必要でした。
- プラグイン エコシステム: Jekyll にはさまざまなプラグインがありますが、エコシステムは、特に JavaScript フレームワークとインタラクティブ コンポーネントの統合に関して、私たちが望んでいたほど広範でも最新でもありません。 さらに、私たちは GitHub Pages を通じてドキュメント サイトをホストしているため、使用できる Jekyll プラグインは限られていました。
- ドキュメント エクスペリエンス: バージョン管理、強力な検索機能、全体的に最新のルック アンド フィールなどの機能を備えた、よりインタラクティブでユーザー フレンドリーなドキュメント エクスペリエンスを求めていました。
Facebook によって開発された Docusaurus は、これらの課題に対処する理想的なソリューションとして登場しました。 オープンソースの静的サイト ジェネレーターはドキュメント サイト向けに特別に設計されており、すぐに使える豊富な機能セットを提供します。
移行プロセス
Jekyll から Docusaurus への移行には、以下で説明するいくつかの重要な手順が含まれます。
計画と準備
私たちは既存のドキュメントを徹底的に監査することから始めました。 これには、ドキュメントのすべてのバージョンを特定すること、ドキュメントの構造が Docusaurus にどのように適合する必要があるかを理解すること、Jekyll で使用していたカスタム機能やプラグインをメモすることが含まれます。
作業の大部分には、Jekyll で使用した HTML と Liquid 構文を組み合わせた警告やタブなどの部分を React コンポーネントと Docusaurus の組み込み機能に変更することが含まれていました。 また、ドキュメントで React コンポーネントを利用したいため、すべての Markdown ファイル拡張子を .md から .mdx に変更する必要もありました。 ドキュメント サイトで最高のエクスペリエンスを確保するには、ScalarDB と ScalarDL の両方のドキュメントのすべてのバージョンにこれらの変更を適用する必要がありました。
セットアップとカスタマイズ
Docusaurus をセットアップするには、Docusaurus CLI を使用して新しいプロジェクトを初期化しました。 これにより、重要なドキュメント サイトの機能が事前に構成された堅牢な出発点が得られました。
そこから、Docusaurus の高度にカスタマイズ可能なテーマを活用しました。 ブランドに合わせてテーマを調整し、バージョンのサポート、ページ上のタブ、Algolia DocSearch などの必要なコンポーネントとカスタマイズを組み込んで、ユーザー エクスペリエンスを向上させました。 私たちが行ったカスタマイズの多くは他の組織のドキュメント サイトに共通するものであったため、これらの機能を最初から構築することなくこれらのカスタマイズを実装することができました。
テストと展開
Jekyll から Docusaurus への移行後、新しいドキュメント サイトを展開する前に、リンク、タブ、警告、バージョン ナビゲーション、およびその他の側面が正しく機能していることを確認するために広範なテストを実行しました。 Docusaurus CLI には、サイトが正しく構築されていることを確認し、壊れたリンクがないかチェックするための便利なツールが含まれています。ドキュメント サイトの所有者は、内部リンク、外部リンク、またはアンカーがいつナビゲートできなくなるかわからない可能性があるため、このツールは特に役立ちます。
重大なエラーを解決した後、GitHub Pages を使用して新しいドキュメント サイトをデプロイし、Docusaurus がセットアップ ガイドの一部として提供するシームレスな CI/CD ワークフローの恩恵を受けました。 さらに、ドキュメント サイトへの各プル リクエストの一部として、サイトが期待どおりにエラーなくデプロイされることを確認するテストが実行されます。
徹底したテストの後、更新されたドキュメント サイトをリリースしました。次の場所にあります。
さらに、私たちのドキュメント サイトはオープン ソースなので、次のリポジトリを自由に参照して、Docusaurus のセットアップ方法を確認してください。
実現されたメリット
Docusaurus への切り替えにより、次のようないくつかの直接的なメリットがもたらされました。
- ナビゲーション エクスペリエンスの向上: 組み込みの階層ナビゲーションにより、ユーザーはサイドバーでカテゴリを展開したり折りたたんだりすることで、より効率的に情報を検索できるようになりました。
- 強化された検索エクスペリエンス: Docusaurus は Algolia DocSearch を正式にサポートしているため、時間の経過とともに改善された検索結果を提供する強化された検索エクスペリエンスをユーザーに提供できます。
- バージョン管理エクスペリエンスの向上: 専用のバージョン管理構造により、ドキュメントの複数のバージョンをより適切に管理および表示できるようになり、異なるバージョンの ScalarDB または ScalarDL を使用するユーザーに対応できるようになりました。
- 実装が簡単なコンポーネントとカスタマイズ: Docusaurus は React に基づいているため、豊富な最新のコンポーネントとテーマが存在します。 コンポーネントとテーマにアクセスできると、大規模なカスタマイズ プロジェクトに取り組む必要が減り、機能のカスタマイズやコーディングをゼロから行うのではなく、コンテンツに集中できるようになります。
- 熱心なコミュニティ サポート: 活発な Docusaurus コミュニティは豊富なコンポーネント、テーマ、サポートを提供しているため、質問への回答を見つけたり、ドキュメント サイトを改善する方法を理解したりするのに、労力や憶測での作業が少なくて済みます。
まとめ
Jekyll から Docusaurus への移行は、ScalarDB および ScalarDL ドキュメント サイトにとって変革的なステップとなりました。 新しく実装された静的サイト ジェネレーターは、ユーザー エクスペリエンスを向上させるだけでなく、ScalarDB と ScalarDL の強化を続ける中で、ドキュメントを効率的に管理および更新できるようになります。 私たちは、この移行がもたらす可能性、特にそれがユーザーや貢献者にどのように役立つかに興奮しています。
別の静的サイト ジェネレーターへの移行を検討している場合、私が共有した経験が洞察とインスピレーションになれば幸いです。
当社のソリューションの詳細については、次の製品ページをご覧ください。
