你該選 Docusaurus 嗎？

Docusaurus 好用嗎？

這是我在 Docsaid 架站超過一年後，最常被問的一個問題。

答案是肯定的，但它好用的原因，跟你想的可能不太一樣。

為什麼我一開始會選 Docusaurus？​

其實我一開始選的是 WordPress.org。（想不到吧？）

因為它的聲量大，很多人用，生態系完整成熟。很多功能都有現成的 plugin 可以用，像是 SEO、社群分享、網站地圖等等。而且 WordPress 的使用者介面也很友善，對於不熟悉程式碼的人來說，簡單易上手。

可是，我會寫程式啊！

會寫程式有時候也是一種詛咒，因為當你一無所知的時候，就照著網路上的教學走就好，沒有太多選擇。

但當你知道有其他選擇時，你就會開始懷疑這個選擇的正確性：這樣真的好？

特別是你知道你「可以」做到某些事情時，例如：

• 我為什麼不能用 Markdown 寫文章？

  其實可以，但需要額外裝 plugin，寫起來沒有開發者工具的語法高亮、版本控管、元資料都難整合。

  ---

• 我為什麼不能用 Git 管理版本？

  其實可以，但大多數 WordPress 的修改都透過後台進行，很難同步到 Git，而且很多內容是儲存在資料庫裡，不是檔案。

  ---

• 我為什麼不能呼叫外部 API？

  其實可以，但要繞過 CORS、寫自訂 JS、還得想辦法在不污染主題的情況下注入前端程式碼。

  ---

你以為你節省了時間，但是實際上你卻浪費了更多時間在這些問題上。

這些問題的解決方案都不是一個簡單的 plugin 就能解決的，反而需要你自己去寫程式碼。

說到底還是要自己寫程式碼，那我還要 WordPress 幹嘛？

而且 WordPress 的 plugin 生態系也不是完美的，很多 plugin 都是由第三方開發的，品質參差不齊，有些甚至會影響網站效能或安全性。

這一來一回之間，到底是賺了？還是虧了？

還有什麼選擇？​

仔細想想我的需求，我最根本的需求是：寫文章。

寫文章本身就是不小的負擔，如果還要花費精力在排版工具上，這沒多久就能讓你心力交瘁。

所以我不只要「寫文章」，還要「寫 Markdown 文章」，這樣我才能專注在內容上，而不是排版上。

基於 Markdown 的靜態網站生成工具很多，各有強項。

我們從網路上找了一些資料，這裡簡單對比一下：

Docusaurus​

1. 最適合技術文件與多語系站點建置： 在「文件導向」、「多語系支援」上表現最佳，強化其作為開發文件網站首選的地位。
2. 前端互動具備一定彈性，但需有 React 經驗： 支援 React 架構，雖然互動性可達尚可，但也使其「學習曲線」相對較難，較適合前端熟手。
3. 維護頻率高、版本控管整合佳，適合多人協作： 適合需要 Git 工作流程的團隊開發情境，並具備活躍的更新頻率。

Hugo​

1. 靜態網站編譯極快，適合追求速度與效率者：Hugo 使用 Go 語言打造，編譯速度為所有框架中最快，部署迅速。
2. 在架構彈性與外掛整合上表現強大：支援高度自訂化與資料來源整合能力，使其成為大型內容網站的熱門選擇。
3. 多語系與前端互動支援較弱，不適合作國際化或動態應用：這些弱點使 Hugo 較偏向單語系內容網站或部落格用途。

Jekyll​

1. 學習曲線最平易近人，適合初學者入門靜態網站：Jekyll 語法簡單，適合非工程背景使用者快速上手 GitHub Pages 部署。
2. 多數功能表現中庸，難以滿足複雜應用：雖然部署、SEO 都不錯，但缺乏強項，使其逐漸被其他框架取代。
3. 生態系與維護動能趨弱，未來延展性有限：相對其他框架，其更新頻率與社群活力明顯下滑，適合低維護個人頁使用。

Hexo​

1. 中文社群活躍，適合中文使用者：雖然國際支援度不高，但中文資源豐富，易於找到教學與主題套件。
2. 上手簡單、部署方便，適合寫作為主的使用者：Hexo 以 Node.js 為基礎，對 JS 熟悉者相當友善，快速建站無壓力。
3. 外掛與多語系支援較弱，不適合長期大型維護專案：較適合用於簡單部落格或個人介紹網站，較難應對多國語言與企業級文件。

Astro​

1. 前端互動與現代技術整合能力最強：支援 React/Vue/Svelte 等現代框架組合，適合打造互動豐富、靜態兼具的網站。
2. 架構彈性高，資料整合能力佳，適合高自訂專案：能接多來源資料、支援複合架構，利於內容驅動或設計導向網站。
3. 多語系、主題生態仍在發展中，學習曲線偏中等：對於需要國際化與即用型模板的使用者來說，目前仍不夠成熟。

它幫我做了哪些事？​

我沒有足夠的時間逐一嘗試，所以憑藉著現有的資料，我選擇了 Docusaurus。

• 文件導向設計，支援 sidebar、breadcrumb 自動產生
• 多語系支援內建，我網站目前有中、英、日三個版本
• Markdown / MDX 撰寫方便，可插入 React 元件
• 預設主題就夠好用，不需大量客製化 CSS
• GitHub Pages 一鍵部署，適合自架站

如果你要問我哪個功能最滿意，我會說是「MDX 撰寫」。

對 React 開發者來說，使用 MDX 插入 React 元件的能力極大提升內容呈現的彈性。有缺什麼功能就直接手搓一個 React 元件就好。

此外，我也幾乎不需處理前端打包、優化、路由設定和多國語系配置等細節。

整體看來，它大概幫我處理掉了 80% 的網站需求，剩下的 20% 就是我自己寫的 React 元件和文章。

有哪些限制？​

雖然 Docusaurus 對於文件型網站或知識庫架設來說非常方便，但使用過程中也有一些明顯的限制與缺點：

1. 不適合高度客製化的動態網站

   Docusaurus 是專為靜態內容生成設計的工具，因此不適合需要大量動態互動或即時資料更新的網站，例如電子商務、論壇或會員系統。若網站需求需要動態渲染（SSR）、頻繁資料互動或後端整合，Next.js、Remix 或 Nuxt 等框架更合適。

   ---

2. React 是唯一內建支援的前端框架

   Docusaurus 使用 React 與 MDX 技術，並無法原生支援其他前端框架（例如 Vue、Svelte、Angular）。若專案團隊熟悉其他框架，或希望未來切換框架時不需大幅改動內容，Docusaurus 就會顯得侷限。

   ---

3. 樣式與 UI 調整限制較大

   儘管 Docusaurus 提供內建主題且允許客製化 CSS，但大多數 UI 調整需要透過覆蓋內建元件或重新定義主題才能完成。若需大量客製化 UI 或重新設計視覺風格，反而可能產生大量額外的工作量。

   ---

4. Plugin 擴充有限

   雖然 Docusaurus 的 plugin 生態算是活躍，但相較於 Gatsby、Next.js 或 Hugo 等更成熟的生態系，Docusaurus 第三方 plugin 相對較少。某些需求若官方或社群未提供 plugin，就必須自行開發，可能增加技術維護成本。

   ---

5. 大型網站建置效能問題

   當內容規模非常龐大（數千頁以上）時，Docusaurus 的建置時間可能會明顯拉長。每次新增或調整內容都需重新建置全部網站內容，若網站的內容更新頻繁，將面臨較大的建置效率問題。這時候，更成熟且效能優化更好的 Hugo 可能會更合適。

   提示

   這個問題在最近 V3.6.0 版本中已經有改善，建置速度有明顯提升，詳細使用體驗還需要經過社群驗證。

   ---

6. 部分功能需透過第三方服務實現

   Docusaurus 專注於靜態網站產生，因此像是搜尋（例如 Algolia）、留言系統（例如 Disqus 或 GitHub Issues）、會員登入或資料庫整合都必須透過第三方服務實現，網站內部並不提供內建解決方案。

   ---

7. 學習曲線取決於對 React 的熟悉程度

   雖然 Docusaurus 針對 Markdown 撰寫者非常友善，但若想要進一步善用 MDX，加入 React 元件或客製化功能，使用者必須熟悉 React 與 JSX，對於非前端工程師或新手而言，可能增加入門難度。

---

整體而言，Docusaurus 最佳使用情境是快速建構知識庫、教學文件、或技術內容網站，若需求超出此範圍，以上限制則可能影響使用者體驗與開發效率。

我的使用狀況​

目前我的網站 Docsaid 已經使用 Docusaurus 架構超過一年：

• 累積撰寫 170+ 篇論文筆記
• 支援繁中、英文、日文三語切換
• 包含 blog、docs、papers、playground 等模組
• 自己動手串上了一個後台，提供使用者登入註冊及 API Token 發放功能
• 手搓超過 20+ 個 React 元件，支援不同文章的呈現需求

Docusaurus 雖然不是萬能，但對我這種「內容密集型」的網站來說，它依然是目前最省事、最穩定的解法。

結語：誰適合 Docusaurus？​

我推薦給以下這幾種使用者：

• 想建立大量內容導向網站（技術文件、學習筆記、開源手冊）
• 想做多語系但不想維護複雜的網站架構
• 想低維護成本快速架站
• 願意接受 React 生態系的人（MDX/JS config）

我會繼續用它，也會持續補完 Docusaurus 的使用技巧與元件擴充心得。如果你也在考慮用什麼架站工具，不妨先用 Docusaurus 快速試一版，再決定要不要換。

如果你有特別希望我講點什麼關於 Docusaurus 的內容，歡迎在下方留言告訴我，我會優先考慮寫出來。

祝你架站愉快。