簡介
⚡️ Docusaurus 將協助你在短時間內發布一個漂亮的說明文件網站。
💸 建立客製化科技堆疊很昂貴。相反的，專注在你自己的內容上並只撰寫 Markdown 文件。
💥 準備好了嗎？使用進階功能，例如：版本控制、i18n、搜尋和主題自訂。
💅 檢視最棒的 Docusaurus 網站以獲得靈感，並閱讀一些見證。
🧐 Docusaurus 是一個靜態網站產生器。它建構了一個單頁式應用程式，擁有快速客戶端導覽，利用React 的全部功能，讓你的網站更具互動性。它提供了開箱即用的說明文件功能，但可以創建任何類型的網站（個人網站、產品、部落格、市場登陸頁面等）。
快速入門 ⏱️
透過遊玩，在5 分鐘認識 Docusaurus！
建立一個新的 Docusaurus 網站，並遵循非常短的內嵌教學。
安裝 Node.js 並建立一個新的 Docusaurus 網站
npx create-docusaurus@latest my-website classic
啟動網站
cd my-website
npx docusaurus start
開啟 https://127.0.0.1:3000 並遵循教學。
使用docusaurus.new 立即在您的瀏覽器中測試 Docusaurus！
或線上閱讀5 分鐘教學。
Docusaurus：簡化文件製作
在 Algolia 社群活動 中的此簡報中，Meta 開源團隊 分享了 Docusaurus 的簡短演練。他們介紹了如何開始此專案、啟用外掛程式，以及設定文件製作和部落格等功能。
從 v1 移植
Docusaurus v2+ 已從 Docusaurus v1 完全改寫，並利用徹底現代化的工具鏈。在 v2 正式發布 之後，我們非常建議您使用 Docusaurus v2+ 取代 Docusaurus v1，因為 Docusaurus v1 已被棄用。
許多使用者已經 使用 Docusaurus v2+（趨勢）。
如果符合下列情況，請使用 Docusaurus v2+
- ✅您想要一個現代的 Jamstack 文件製作網站
- ✅您想要一個具有客戶端路由功能的單頁式應用程式 (SPA)
- ✅您想要充分利用 React 和 MDX
- ✅您不需要支援 IE11
如果符合下列情況，請使用 Docusaurus v1
- ❌您不需要單頁式應用程式 (SPA)
- ❌您需要支援 IE11（...是真的嗎？IE 已達生命週期終期，且不再獲得正式支援）
對於想要升級至 v2+ 的現有 v1 使用者，可以遵循我們的 移植指南。
功能
Docusaurus 致力於提升開發人員和貢獻者的體驗。
- ⚛️ 運用 💚 和 React 建構
- 透過 React 進行擴充和自訂
- 提供您自己的 React 元件，全力掌控您網站的瀏覽體驗
- 🔌 可插入
- 使用基礎範本啟動您的網站，然後使用進階功能和外掛程式
- 將您的外掛程式開源，與社群分享
- ✂️ 開發人員體驗
- 立即開始撰寫您的文件
- 統一的設定入口點，讓貢獻者更容易維護
- 增量建置快如閃電，變更後可熱重載
- 基於路由的程式碼和資料分割
- 輕鬆發布至 GitHub Pages、Netlify、Vercel 及其他部署服務
我們的共同目標是幫助您的使用者快速找到他們需要的資訊，並且更了解您的產品。我們分享我們的最佳實務，協助您建置優質的文件網站。
- 🎯 友善搜尋引擎
- 為所有路徑靜態產生 HTML 檔案。
- 頁面特定的搜尋引擎最佳化，協助您的使用者直接在您的官方文件找到與其問題相關的內容。
- 📝 搭配 MDX
- 透過嵌入 Markdown 的 JSX 和 React 撰寫互動式元件。
- 在即時編輯器中分享您的程式碼，讓使用者瞬間愛上您的產品。
- 🔍 搜尋：您的整站皆可搜尋。
- 💾 文件版本管理：協助您讓文件與專案版本保持同步。
- 🌍 國際化 (i18n)：翻譯您的網站，提供多國語言版本。
Docusaurus v2+ 注重無障礙協助，讓所有使用者都能順利存取，並提供極快的速度。
- ⚡️ 極速。Docusaurus v2+ 遵循 PRPL 模式，可確保您的內容載入飛快。
- 🦖 無障礙存取。重視無障礙存取，讓所有使用者都能同樣順暢地存取您的網站。
設計原則
- 學習門檻低。Docusaurus 易於學習和使用，因為 API 非常小。大多數事情仍能讓使用者執行，即使他們需要花費更多時間和程式碼才能完成。沒有抽象化勝過有錯誤的抽象化，我們不希望使用者必須處理錯誤的抽象化。必聽的演講—最小 API 表面。
- 直覺。使用者在瀏覽 Docusaurus 專案的專案目錄或新增新功能時，不會感到不知所措。它應該看起來直覺，而且容易在使用者熟悉的做法上建構。
- 階層化架構。我們的層級堆疊（內容/主題/樣式）之間的關注點應明確區分——經過良好抽象和模組化處理。
- 明智的預設值。我們會為使用者套用常見且熱門的效能最佳化和組態，但開放他們覆寫的權限。
- 沒有供應商鎖定。我們極力建議使用者使用預設外掛程式或 CSS，但並未強制要求。由於我們已針對某些核心基礎架構（例如 React Loadable 和 React Router）進行預設效能最佳化，因此無法替換它們，但對於較高層級的架構則不在此限。使用者擁有 Markdown 引擎、CSS 框架、CSS 方法和其他架構的選擇權。
我們相信，對於開發人員來說，了解函式庫的運作原理有助於我們更有效地使用它。因此，我們致力於說明 Docusaurus 的架構和各種組件，並希望閱讀文件的使用者能更深入地瞭解此工具，並更熟練地使用它。
與其他工具的比較
在所有靜態網站產生器中，Docusaurus 獨特專注於文件網站，並有許多開箱即用的功能。
我們也研究過其他主要的靜態網站產生器，並想分享我們對比較的見解，希望能幫助您瀏覽市面上的各種選擇。
Gatsby
Gatsby 搭載許多功能，擁有豐富的外掛程式生態系統，並能執行 Docusaurus 能做的一切事情。當然，學習曲線比較陡這是代價。Gatsby 在各方面表現都很出色，適合建置各種類型的網站。另一方面，Docusaurus 嘗試在一個方面做得非常好 - 成為寫作和發布內容的最佳工具。
GraphQL 也是 Gatsby 的核心，儘管您不一定需要 GraphQL 來建置 Gatsby 網站。在建置靜態網站時，大多數情況下您不需要 GraphQL 提供的彈性。
Docusaurus v2+ 的許多面向受到 Gatsby 中最佳事物的啟發，並且是完美的替代方案。
Docz 是 Gatsby 主題，用於建置文件網站。它目前的特色少於 Docusaurus。
Next.js
Next.js 另一套熱門的混合式 React 框架。它能協助您建置良好的文件網站，但並未偏好文件用例，且需要花費更多的工作才能實作 Docusaurus 開箱即用的功能。
Nextra 是一個建立在 Next.js 之上的意見型靜態網站產生器。它目前的特色比 Docusaurus 少。
VitePress
VitePress 和 Docusaurus 有很多相似之處——兩者都專注於以內容為主的網站，並在開箱即用時提供客製化文件功能。然而，VitePress 是由 Vue 驅動，而 Docusaurus 是由 React 驅動。如果你想要一個基於 Vue 的解決方案，VitePress 將會是一個不錯的選擇。
MkDocs
MkDocs 是一个流行的 Python 靜態網站產生器，其價值主張與 Docusaurus 相似。
如果你不需要單頁應用程式，也不打算利用 React，它會是一個不錯的選擇。
Material for MkDocs 是個很漂亮的佈景主題。
Docsify
Docsify 讓建立文件網站變得簡單，但它不是靜態網站產生器，而且對 SEO 不友好。
GitBook
GitBook 有著非常簡潔的設計，並且已被許多開源專案使用過。隨著它將重點轉向商業產品，而不是開源工具，它的許多需求不再符合開源專案文件網站的需求。因此，許多人轉向其他產品。你可以 在此處 閱讀關於 Redux 切換到 Docusaurus 的資訊。
目前，GitBook 僅對開源和非營利團隊免費。Docusaurus 對所有人都是免費的。
Jekyll
Jekyll 是最成熟的靜態網站產生器之一，一直以來都是很棒的工具——事實上，在 Docusaurus 之前，Facebook 大多數的開源網站都是建構在 Jekyll 上！它的入門非常簡單。我們希望帶來與使用 Jekyll 建立靜態網站相似的開發人員體驗。
與使用 <script /> 標籤加入靜態產生的 HTML 和互動性相比，Docusaurus 網站是 React 應用程式。我們希望透過使用現代 JavaScript 生態系統工具，在文件網站的效能、資源組建管線和最佳化，以及易於設定等方面建立新標準。
隨時掌握最新資訊
少了什麼嗎？
如果您發現文件有任何問題，或者有建議要如何改善文件或整體專案，請提交問題回報給我們，或發推文並提及@docusaurus Twitter 帳戶。
對於新功能要求，您可以在我們的功能要求看板（Canny）上發布貼文，這是一個方便的路線圖製作工具，同時支援依據按讚數排序，這會提供核心團隊更理想的指標來得知對於什麼功能的需求量較高，相較之下，GitHub 問題較難進行分類。請避免為了新功能（尤其是大型功能）提出 Pull Request，因為可能已經有人在進行開發，或是已納入我們的路線圖。請先與我們討論！