跳到主要內容

在不到 2 小時內將 Profilo 轉換為 Docusaurus 的方法

·閱讀 6 分鐘
Christine Abernathy
Christine Abernathy

「Joel 和我在討論建立網站的問題，以及如果可以在啟動時使用該網站會有多好。因此我挑戰自己加入 Docusaurus 支援。只花了 1 個半小時。我將透過 PR 傳送附加的資料給您，讓您可以看一下並表示是否喜歡。您加入文件的工作流程與編輯那些 Markdown 檔案不會差太多。」

— 傳送給 Profilo 團隊的備忘錄

這是使用 Docusaurus 建立 Profilo 網站的一段相當簡短的歷程。

Profilo 是 Android 程式庫，用來從實際環境收集效能追蹤資訊，於今年稍早宣佈。此專案已 發布於 GitHub，其中有不到 一握 Markdown 檔案用來說明其功能，沒有任何網站展示品牌並突顯其標誌。手邊的任務就是要將這些既有的文件和標誌轉換成網站。

一般來說，當你使用 Docusaurus 建立網站時，你可以執行以下作業：

  1. 使用 Docusaurus 指令產生範本網站。
  2. 自訂產生的範本檔案，套用你想要的網站色彩和專案設定（例如：網站和 GitHub 連結）。
  3. 建立網站內容。
    1. 新增你的文件和任何支援資產。
    2. 自訂 Docusaurus 提供的預設登入頁面，以符合你的需求。
    3. 設定預設網站導覽檔案。
  4. 發布網站並設定其在未來變更時如何發布。

由於我已有現成的 Markdown 檔案，因此我不用產生核心內容，只需要確定 Docusaurus 能處理這些檔案，方法是新增預期的中繼資料到這些檔案。因此，大部分的工作在於自訂 Docusaurus 提供的預設值。

已執行步驟的概觀​

以下是轉換成網站的執行步驟概觀。稍後我會在其中一個區段討論一些設計面向。

設計和色彩

  1. 從設計師取得所有想要的標誌格式。我必須建立 .favicon 的格式。
  2. 使用 http://paletton.com/ 工具找出網站上頗合適的主色和輔色，此工具很好用！

網站初期設定

  1. 在 GitHub 上 Fork Profilo 專案，並建立 Fork 的本機複製，以設定網站。
  2. 使用 安裝說明建立 Docusaurus 初始網站。
  3. 刪除 docs-examples-from-docusaurus 和 website/blog-examples-from-docusaurus 資料夾，因為我們不需要這些資料夾。Profile 已有現成的文件可以使用，現在也不需要部落格。

建立內容

  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. 傳送一個 pull request 至專案。
  2. 在設計師對於我選擇的色彩表示驚訝（我並非設計師）後更新色彩。
  3. 更新色彩並更新 PR。
  4. 接著 PR 被接受並 合併。太棒了！

網站發布

  1. 透過從命令列執行 Docusaurus 發布指令碼，推播第一版網站

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

  2. 使用 Docusaurus 提供的說明 設定 CircleCI。此部分有 2 個 PR，第一個 用於初始設定，第二個 用於確保 CircleCI 只會在 master 分支的變更中觸發（感謝 Joel Marcey！）。

最終網站已發布在 https://facebookincubator.github.io/profilo/。從初始 PR 階段到回應檢閱回饋並發布網站，總共耗時 1.5 小時。

設計 ​

以下是在傳送第一個 pull request 時初始網站的樣貌

The website's front page, with a quite bright and saturated red color as the primary color, closely resembling the Profilo logo color, making the logo unrecognizable in the navbar

在內容建立期間，大部分的時間都花在挑選可以與現有標誌合理搭配的色彩。這些色彩是設計師回饋的良好起點。我使用 Photoshop 來取樣標誌的不同部分。

Picking colors in Photoshop, with the Profilo logo and the main working area in the background and a color picker dialog in the foreground, selected to a red shade

接著我取得該色彩的 RGB 表示值，並將其設定為 Paletton 上的基本色彩。然後這個網站提供給我不同的色彩選項，可以透過編輯 Docusaurus 網站設定檔來嘗試用在網站上。

Using Paletton to generate a full palette from the red shade selected. There's a color wheel showing all hues on the left, and a square showing various shades of red on the right.

所選取的主題和次要色彩是設計師回饋的良好起點。

也對 Docusaurus 所產生的預設網站進行了修改。這些變更主要在於簡化頁尾和建立 Profilo 的自訂著陸頁，其中列出專案功能。

以下是如何最終網站的樣貌

The website's front page, with a much darker red color as the primary color, making both the logo and the primary-colored title text clearly legible.

這是顯示核心內容的範例頁面，在本例中是「開始使用」頁面

A doc page with the sidebar on the left quarter of the screen and the main content occupying the rest. Some text is using the primary color and the main body uses multiple kinds of typesetting including bold, list, and code

這也顯示了透過編輯 website/sidebars.json 設定側邊欄的架構。

最後，我不需要煩惱響應式設計處理。透過 Docusaurus 就可輕鬆得到這個功能！

Mobile screenshots of the front page and sample doc page. The layout is automatically adjusted to make it appear more natural. The doc sidebar is hidden behind a button.

最終感想​

Profilo 工程師很樂意看到他們的作業流程不須更改，就可以更新現有內容。他們仍可繼續使用 Markdown 文件。未來當加入新的文件時，這一點仍然正確，不過若需要更新側邊欄導覽，則可能需要一些設定變更。

Docusaurus 所提供的基礎架構能輕鬆將 Markdown 文件轉換成運作良好的網站。即使這個專案只有三個文件，這也讓 Profilo 看起來更專業。因此，短暫的執行投資非常值得。