跳到主要內容

簡介 Docusaurus

·閱讀 9 分鐘
Joel Marcey
Joel Marcey
Meta 的開發倡導者

我們很樂意介紹Docusaurus來協助你管理一個或多個開放原始碼網站。

我們Docusaurus基於下列原因：

  1. 重點在於撰寫良好的文件，而不是網站的基礎架構。
  2. 提供許多我們的開放原始碼網站需要的功能，例如部落格支援、搜尋和版本控制。
  3. 大家可以一次輕易地推播更新、新功能和錯誤修正。
  4. 最後，提供所有開放原始碼專案一致的觀感和體驗。

Docusaurus 是一個工具，其設計宗旨是讓團隊可以輕鬆地發布文件網站，而不用擔心基礎架構和設計細節。使用者只要提供用 Markdown 撰寫的文件檔案、自訂使用 React 撰寫的提供首頁，以及一些設定修改即可。Docusaurus 負責處理其他部分，包括提供預設樣式、網站格式和簡易的文件導覽。使用者可以透過一個簡單的初始化腳本使用 npm 或 yarn 安裝，馬上開始使用，並 建立一個可立即運作的範例網站。

Docusaurus 還提供了現成可用且基本的網站和文件功能，包括 網誌支援、國際化、搜尋 和 版本控管。雖然有些專案可能用不到這些功能，但啟用這些功能通常只需要更新設定選項，而不需要從最根本的基礎架構開始新增。隨著愈來愈多功能新增至 Docusaurus，使用者可以輕鬆更新至最新版本。這樣做的方式很簡單，只要執行 npm 或 yarn update 以及更新設定選項即可。每次有新的功能被加入時，使用者或團隊就不再需要手動重新打造整個網站基礎架構。

Docusaurus 的誕生​

Facebook 最初啟動其開源計畫時，許多團隊為其各項開源計畫實作了一個自訂網站。當開源計畫團隊被要求協助專案團隊改善其文件時，這種做法衍生出了挑戰。由於每個網站都是獨一無二的，加入部落格、一致的導覽列、搜尋功能等基本基礎架構成為具有挑戰性的任務。

開源團隊試圖透過提出一個基於 Jekyll 的標準範本來減輕這個問題，這個範本可以做為專案網站的起點。我們請新專案將範本原始檔手動複製到其儲存庫，撰寫其文件並發布。這個範本方法已被大部分已推出的開源計畫採用；有些現有專案甚至也將其自訂網站實作轉換至新的範本。

使用「將範本複製到您的存放庫」方法的問題在於，即使平台一致，也會讓更新維護變得不可維護，因為這個模板已經有許多專案在使用中。這是因為在專案將模板複製到他們的存放庫之後，我們就失去了模板的控制權。專案可以自由地修改模板，並套用他們自己專案專用的功能在上面。因此，儘管專案共用相同的網站產生平台，但現在有足夠的分歧，而無法利用我們在模板中新增的新功能。我們沒有辦法要求所有目前的專案都「複製」模板的新版本，因為這樣可能會損毀他們現有的網站，或是移除他們自行新增的功能。反之，我們必須對每個專案逐一地手動套用更新。當專案開始向我們的團隊要求模板中的國際化支援，並要求對範本結構和產生方式進行低階變更時，這樣的情況變得非常有問題。

因此，我們開始思考我們可以採取什麼措施來減輕維護網站更新和在整個作品集中維持一致性的難題。我們也希望多個專案共用同一個網站產生軟體。我們希望他們可以從同一個範本開始，但對於自訂和調整他們的網站主題，還是必須保持彈性，以符合他們的需求。他們應該可以延伸和自訂他們的網站，但是，當我們使用修正和功能更新基礎架構時，專案應該是可以用簡單的方式更新，而且不會有重大變動。

Docusaurus 誕生了！

在 Facebook，Docusaurus 讓我們可以快速讓不同的專案建立並運行文件網站，特別是對於沒有太多網頁開發經驗，或是主要想要透過一個基本網站展示他們的專案的團隊來說。Docusaurus 已經支援需要更多進階功能的網站，例如針對 Jest 的國際化，以及針對 React Native 的版本控制。當不同的專案為他們的網站要求新的功能時，這些功能就會被新增到 Docusaurus 中，並同時提供給所有專案！總括來說，這樣可以大幅減少維護不同專案的不同網站所需的工作量。我們的團隊可以透過花更多時間新增功能、修正問題，和撰寫說明文件，來專注於讓他們的專案更健全。

開始運行​

我們希望使用 Docusaurus 運行的網站核心就是簡單易用。使用一個安裝命令和一些簡單的組態，您實際上就可以有一個正在運作的預設網站。

當您執行 docusaurus-init，您會看到類似下列的結構

root-of-repo
├── docs-examples-from-docusaurus
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   ├── example-doc4.md
│   └── example-doc5.md
├── website
│   ├── blog-examples-from-docusaurus
│   │   ├── 2016-03-11-blog-post.md
│   │   └── 2017-04-10-blog-post-two.md
│   ├── core
│   │   └── Footer.js
│   ├── node_modules
│   ├── package.json
│   ├── pages
│   ├── sidebars.json
│   ├── siteConfig.js
│   └── static

除了 node_modules 和 package.json 外，您看到的所有目錄和檔案是你自訂和新增內容到你基於 Docusaurus 的網站。 docs 資料夾是你新增代表文件的文件；blog 資料夾是你新增給文件 部落格文章；siteConfig.js 是你製作大多數 自訂網站；sidebars.json 是你維護文件的 側邊欄 佈局和內容；pages 資料夾是你新增 自訂 網站頁面；static 資料夾是你放置所有靜態資源（例如，CSS 樣式表和圖片）；而 core 資料夾是你自訂網站核心組件的地方，在此範例中是頁尾。

Docusaurus 如何運作？​

Docusaurus 主要以 JavaScript 和 React 編寫，取代我們在舊範本中使用的 Jekyll。我們使用 Remarkable 渲染我們的標記，並使用 highlight.js 突顯我們的程式區塊語法。Docusaurus 功能的核心在 lib 目錄 的 Docusaurus 存放庫 中。一般結構如下

root-of-Docusaurus
├── lib
│   ├── core
│   ├── server
│   │   ├── generate.js
│   │   ├── server.js
│   │   └── ...and more files
│   ├── static
│   ├── build-files.js
│   ├── copy-examples.js
│   ├── generate-feed.js
│   ├── publish-gh-pages.js
│   ├── rename-version.js
│   ├── start-server.js
│   ├── versions.js
│   └── write-translations.js

這裡的關鍵檔案是 build-files.js 和 start-server.js。這兩個檔案有很多相似點：build-files.js 用來建立要由外部網路伺服器提供的實體成品。start-server.js 用來執行 Docusaurus 伺服器並在你的電腦上測試網站。兩個檔案都執行以下一般程序，以使用所有標記和組態來建立可執行的網站

  1. 在 siteConfig.js 處理你的網站設定
  2. 從文件資料夾中所有標記檔案讀取文件對應資料。
  3. 根據從對應資料萃取的 ID 建立文件的目錄清單。
  4. 將標記轉換成 HTML，包括執行連結置換。
  5. 這些檔案將放在已編譯網站的 build/docs 資料夾中，且任何已翻譯的版本將放在 build/docs 資料夾中的語言特定資料夾。
  6. 部落格文章重複步驟 1-3。
  7. 部落格檔案將放在已編譯網站的 build/blog 資料夾中。
  8. 閱讀 main.css 檔案並將任何使用者自訂 css 連接成主 css 檔案，該檔案會在編譯網站的 build/css 目錄中。
  9. 將圖片複製到編譯網站的 build/img 目錄中。
  10. 選取任何已新增到網站 pages 資料夾的自訂頁面，並將其編譯或複製到編譯網站的根目錄 build 目錄中。任何已翻譯的版本都將放入 build 中以語言為主的資料夾中。
  11. 建立 CNAME 和 sitemap.xml 檔案，並將其加入 build。

請注意，此程序並未完全考量到翻譯或版本控制如何運作。這些功能的基本細節將保留供日後撰寫的部落格文章使用。

已編譯網站的最終結構看起來會類似

build
├── website
│   ├── CNAME
│   ├── blog
│   ├── css
│   ├── docs
│   ├── en
│   ├── help.html # custom page
│   ├── img
│   ├── index.html # landing page
│   ├── sitemap.xml
│   └── users.html # custom page

社群​

歡迎您對 Docusaurus 提供意見回饋，無論您是要用於自己的網站、想協助 Docusaurus 核心技術，或者僅是有些問題。於GitHub 和Twitter追蹤我們。

致謝​

如果沒有其他 Docusaurus 團隊成員的努力協助，Docusaurus 將無法誕生：Eric Nakagawa、Hector Ramos、Eric Vicenti，以及Frank Li － 前 Facebook 實習生，協助建置核心技術和功能。

也要特別感謝最早採用 Docusaurus 的人

如果沒有他們致力於建立或將其網站遷移到平台上，我們不可能會有今天的成果。

資源​