Profiloを2時間以内にDocusaurusに移行した方法

「Joelと私はウェブサイトを持つことについて話し合っており、立ち上げ時にウェブサイトがあればよかったのにと思っていました。そこで、私はDocusaurusのサポートを追加するという課題に挑戦しました。1時間半強しかかかりませんでした。追加した内容でプルリクエストを送信するので、見て気に入るかどうか確認してください。ドキュメントを追加するためのワークフローは、これらのMarkdownファイルを編集するのとそれほど変わりません。」

— Profiloチームに送信されたメモ

これは、Docusaurusを使用してProfiloウェブサイトを作成するまでの、かなり短い道のりの物語です。

本番環境からパフォーマンストレースを収集するためのAndroidライブラリであるProfiloは、今年初めに発表されました。このプロジェクトは、GitHubで公開されましたが、その機能を説明するMarkdownファイルはほんの一握りで、ブランディングを紹介したりロゴを強調したりするウェブサイトはありませんでした。目の前のタスクは、これらの既存のドキュメントとロゴをウェブサイトに変えることでした。

一般的に、Docusaurusでウェブサイトを作成する場合、次の手順を実行します。

1. Docusaurusスクリプトを使用してテンプレートウェブサイトを生成します。
2. 生成されたテンプレートファイルを、目的のサイトの色とプロジェクト構成（例：ウェブサイトとGitHubのリンク）に合わせてカスタマイズします。
3. ウェブサイトのコンテンツを作成します
   1. ドキュメントとサポートアセットを追加します。
   2. Docusaurusによって提供されるデフォルトのランディングページをニーズに合わせてカスタマイズします。
   3. デフォルトのサイトナビゲーションファイルを構成します。
4. ウェブサイトを公開し、今後の変更のために公開する方法を設定します。

既存のMarkdownファイルがあったため、コアコンテンツを生成する必要はなく、期待されるメタデータを追加することでDocusaurusがファイルを処理できることを確認するだけで済みました。したがって、作業の大部分は、Docusaurusによって提供されるデフォルトのカスタマイズで構成されます。

実行した手順の概要

ウェブサイトへの変換に必要な手順の概要を以下に示します。デザインの側面については、後のセクションで説明します。

デザインと色

1. デザイナーから必要なすべてのロゴ形式を取得しました。 _favicon_ のロゴを作成する必要がありました。
2. http://paletton.com/ツールを使用して、まずまずのプライマリとセカンダリのウェブサイトの色を作成しました。これは非常に便利です。

初期ウェブサイトのセットアップ

1. GitHubでProfiloプロジェクトをフォークし、フォークのローカルクローンを作成してウェブサイトをセットアップしました。
2. インストール手順に従って、初期Docusaurusウェブサイトを作成しました。
3. `docs-examples-from-docusaurus` と `website/blog-examples-from-docusaurus` フォルダは必要ないため、削除しました。Profiloには使用できる既存のドキュメントがあり、現時点ではブログは必要ありませんでした。

コンテンツの作成

1. `docs` フォルダにある既存のMarkdownファイルにメタデータを追加しました。例：

   ---
   id: architecture
   title: Architecture
   sidebar_label: Architecture
   ---

2. ロゴアセットを `website/static/img` フォルダに追加しました。

3. ランディングページである `website/pages/en/index.js` を変更して、Profiloの機能を強調しました。

4. フッターである `website/core/Footer.js` を変更して、Profilo向けに簡素化しました。

5. ウェブサイト構成ファイルである `website/siteConfig.js` を編集して、以前に選択したプライマリとセカンダリのの色を指定しました。

6. サイドバーナビゲーションを指定する `website/sidebars.json` を変更しました。すべてのドキュメントをリストし、Markdownファイルに追加されたメタデータに基づいてカスタマイズしました。

7. ウェブサイト構成ファイルを編集して、GitHubのプロパティ、ロゴ画像、ヘッダーリンク、ウェブサイトリンクを指定しました。

8. このフェーズ全体でウェブサイトをローカルでテストしました。（ `website` フォルダから `yarn start` を実行してサーバーを起動しました。）

フィードバックとレビューの変更

1. プロジェクトにプルリクエストを送信しました。
2. デザイナーが私が選択した色に当然のことながら息を呑んだ後、色を更新しました（IANAD）。
3. 色を更新し、プルリクエストを更新しました。
4. プルリクエストは承認され、マージされました。やったー！

ウェブサイトの公開

1. コマンドラインからDocusaurus公開スクリプトを実行して、最初のウェブサイトバージョンをプッシュしました

   USE_SSH=true \
     GIT_USER=caabernathy \
     CURRENT_BRANCH=master \
     yarn run publish-gh-pages

2. 提供されているDocusaurusの指示に従ってCircleCIを構成しました。これには2つのプルリクエストがありました。最初は初期構成用、2番目はCircleCIがマスターブランチの変更に対してのみトリガーされるようにするためです（Joel Marceyに感謝！）。

最終的なウェブサイトはhttps://facebookincubator.github.io/profilo/に公開されました。最初のプルリクエストの段階に到達するまでに1.5時間かかり、レビューフィードバックに対応してウェブサイトを公開するまでにさらに30分ほどかかりました。

デザイン

最初のプルリクエストが送信されたときの初期ウェブサイトの外観は次のとおりです。

コンテンツ作成のほとんどの時間は、指定されたロゴで reasonably well 機能する色の選択に費やされました。これらの色は、デザイナーのフィードバックを得るための良い出発点となりました。Photoshopを使用して、ロゴのさまざまな部分をサンプリングしました。

次に、色のRGB表現を取得し、Palettonでベースラインの色として設定しました。ウェブサイトでは、Docusaurusウェブサイト構成ファイルを編集することで、ウェブサイトで試すことができるさまざまな色のオプションが提供されました。

選択されたプライマリとセカンダリのの色は、デザイナーのフィードバックを得るための良い出発点となりました。

Docusaurusによって生成されたデフォルトのウェブサイトにも変更が加えられました。これらの変更は、主にフッターの簡素化と、プロジェクトの機能をリストしたProfiloのカスタマイズされたランディングページの作成に関するものでした。

最終的なウェブサイトの外観は次のとおりです。

これは、コアコンテンツ（この場合は「はじめに」ページ）を示すサンプルページです。

これは、 `website/sidebars.json` を編集することで設定されたサイドバー構造も示しています。

最後に、レスポンシブデザインの処理について心配する必要はありませんでした。Docusaurusでは、これがすぐに使えるようになっています。

最終的な考え

Profiloのエンジニアは、既存のコンテンツを更新するためにワークフローを変更する必要がないことを喜んでいました。彼らはMarkdownファイルで作業を続けることができました。サイドバーナビゲーションを更新する必要がある場合は、構成の変更が必要になる場合がありますが、新しいドキュメントが追加される場合でも、これは将来も当てはまります。

Docusaurusによって提供されるインフラストラクチャにより、Markdownファイルを機能するウェブサイトに簡単に変換できました。プロジェクトには3つのドキュメントしかありませんでしたが、これによりProfiloはよりプロフェッショナルな外観になりました。そのため、短時間投資して完了する価値は十分にありました。