Skip to main content

Docusaurus 是什麼? 可以吃嗎?

先從身世說起​

Docusaurus 是由 Facebook 開發維護，並且開放原始碼的一個靜態網站產生器，底下的框架為 React.js。

它的名字是 Document 和 Saurus 這兩個字的組合，而且有一個很貼切的 Logo：一隻小恐龍，而牠的肚子正巧就是文件的形狀。

Docusaurus logo

Docusaurus 早在 2017 年之前就發表了它的第一個版本，接著很快的在 2018 年就展開了 2.0 版的改版計劃，並且釋出多個 alpha 及 beta 版。

在 2022 年的 8 月 1 日發表了 2.0.0 正式版。

我個人則是從 2.0.0-alpha.72 版左右開始接觸它，一直用到現在。

也把我的部落格從原本的 Jekyll 框架改成了 Docusaurus，也就是大家現在看到的版本。

Docusaurus 的誕生​

Docusaurus 又是怎麼被生出來的呢?

話說，在很久很久以前， Facebook 裡面建立了很多開放原始碼的專案，每個團隊都會為他們的專案打造一個專屬的網站。

隨著這樣的工作變得冗雜，便有人向開放原始碼計劃的團隊要求，看能不能在文件這個部份提供什麼協助。

因為每個網站都是獨立的，要為它們打造部落格、一致的導覽、搜尋功能等等，就變得非常有挑戰性。

當時的開放原始碼計劃團隊嘗試透過提供標準化 Jekyll 樣版的方式來減輕這些問題，好讓大家有一個好的起始點來建立他們的專案網站。

而當初的流程是要大家手動複製樣版的原始碼到他們自己的 repo 、 撰寫文件庫然後發佈。

大多數的團隊都從善如流，甚至有團隊把他們原本的自已客製化出來的網站轉換成用新範本的版本。

但是手動複製樣版的原始碼到自己的 repo這個方法還是終究造成各個專案的不一致，畢竟各專案的成員還是可以任意更動他們複製過去的樣版原始碼。

隨著時間拉長，不同團隊間的樣版原始碼就越來越不一致，就算原始的樣版推出了新的版本，也沒有一個好的方法能套用到其他專案上。

所以大家又向開放原始碼計劃團隊敲碗了。

這次，開放原始碼計劃團隊想要一次解決幾個問題：

  1. 每個專案的樣版都要可以更新，而且一致性不會被破壞。
  2. 多個專案可以共用同一個網站產生器。
  3. 從同一個樣版出發，但是提供彈性給每個團隊去依照需求客製化網站的樣式。
  4. 每個團隊可以客製化或是擴充他們要的功能，日後專案樣版還是可以輕易的更新，而不需要做什麼重大的調整。

基於以上幾個願望，就這樣催生出了 Docusaurus。

在 Facebook 裡，越來越多團隊開始使用 Docusaurus - 尤其是對於網頁技術不那麼熟悉的團隊，以及那些主要只想要有個基本的網站來展示他們的專案的團隊。

Docusaurus 也支援了不同的團隊的需求，例如 Jest 需要多語系、以及 React Native 需要多版本的支援。

只要有團隊提出需求，它們就會被加到 Docusaurus 裡，同時提供給所有的團隊使用。

各個團隊也就能更專注的把時間投入在開發功能、修復 bug 以及撰寫文件這幾件事上面，而不用再去煩惱如何打造和維護專案網站。

Docusaurus 有哪些特色呢?​

  • 📦 安裝容易、開箱即用：只要使用官方的樣版，無需太多設定，幾分鐘之內就可以架出一個包含文件庫與部落格的網站。
  • 🧩 支援 plugin：文件庫和部落格等等模組都以 plugin 方式封裝，而且有越來越多的第三方 plugin 可用。
  • 🛠 高可客製化：所有模組都元件化，從整個網站的外觀到單一元件都可以客製。
  • 📝 易撰寫：基本上，只需要學會 Markdown 語法，就可以寫出格式一致而且精美的文章，只需要專注在內容，不需要煩惱樣式和排版問題。
  • 🧑‍💻 開發者友善：不論是程式碼高亮、數學公式、流程圖等等，都可以輕鬆呈現。
  • 🧑‍🤝‍🧑 部落格支援多作者：同一篇部落格文章可以有多位作者共篇，且可以列出所有人名。
  • 📚 多版本支援：可以輕鬆製作出不同版號的內容，並透過下拉式選單供使用者切換不同版本的內容。
  • 🌏 多語系支援：框架本身支援多語系，我們只需要專注在內容，就可以實作出一個多語系的網站。
  • 🔍 全文檢索：預設以 Algolia 作為全文檢索平台，並可以免費使用原本需要付費的爬蟲和後台等功能。
  • 👁️‍🗨️ SEO 友善：透過獨立、靜態的 HTML 檔，讓每個路徑都是可以被存取的。
  • 🚀 易佈署：輕鬆就能佈署到 GitHub Pages 、 GitLab Pages 、Netlify 及 Vercel 等等平台。

有哪些大咖在用 Docusaurus?​

因為算是 React.js 親兒子的關係， 和 React.js 相關框架的官網或是說明文件也都直接用它來打造，例如：

因為它原生樣版就內建文件庫和部落格，所以也有越來越多技術類的官網用它來打造，比較知名的例如：

Docusaurus 適合用在哪些地方?​

  1. 技術文件的文件庫：站在多版本支援和多語系支援這兩個強大的功能的肩膀上，用 Docusaurus 來實作技術文件可以省去非常多的工。
  2. 個人部落格：Docusaurus 也可以讓我們輕鬆的客製成只有部落格的功能。
  3. 產品官網：高彈性的結構和靜態頁面本來就是 Docusaurus 的強項，用它來打造產品官網直接就支援 Responsive 的功能。
  4. 其它：除了上述三種，也有人拿 Docusaurus 來搭建 Wiki 和 Covid-19 統計網站。
  5. 混合型網站：Docusaurus 也支援在同一個站台裡面包含多個文件庫和部落格，也就是多個文件庫和部落格混在一起做成瀨尿牛丸的概念。

好框架，不用嗎?