簡介
⚡️ Docusaurus 將協助您 快速建立美觀的說明文件網站。
💸 建立自訂技術堆疊代價昂貴。與其如此，不如 專注於內容，撰寫 Markdown 檔案就好。
💥 準備了解更多功能了嗎？請使用 進階功能，例如版本管理、i18n、搜尋及佈景主題自訂。
💅 查看 最佳的 Docusaurus 網站 以獲得靈感，並閱讀部分 見證。
🧐 Docusaurus 是一個 靜態網站產生器。它會建立一個 單頁應用程式，具備快速的用戶端導覽功能，並利用 React 的強大功能讓您的網站具互動性。它提供現成的 說明文件功能，但也可以用來建立 任何類型的網站（個人網站、產品、部落格、行銷著陸頁等）。
快速入門 ⏱️
透過操作瞭解 Docusaurus，只需 5 分鐘！
建立新的 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
- ✅一個現代的 Jamstack 說明文件網站
- ✅一個具有客戶端路由的單頁式應用程式 (SPA)
- ✅React 和 MDX 的完整能力
- ✅您不需要支援 IE11
如果您需要下列事項，請使用Docusaurus v1
- ❌您不需要單頁式應用程式 (SPA)
- ❌您需要支援 IE11（...您需要嗎？IE 已屆使用壽命終點，且不再受到官方支援）
對於想要從 v1 升級到 v2 的現有 v1 使用者，您可以參考我們的遷移指南。
功能
Docusaurus 建置時高度重視開發人員和貢獻者的體驗。
- ⚛️ 以 💚 和 React 建置
- 延伸和自訂 React
- 提供您自己的 React 組件，完全掌控網站瀏覽體驗
- 可插入:
- 使用基本範本啟動您的網站，然後使用進階功能和外掛程式
- 開放原始碼，將您的外掛程式與社群分享
- ✂️ 開發人員體驗
- 立刻開始撰寫您的文件
- 通用組態切入點，讓貢獻者能更容易進行維護
- 熱重載搭配更動後的閃電快速增量建置
- 以路由為基礎的程式碼和資料分割
- 輕鬆發佈到 GitHub Pages、Netlify、Vercel 和其他部署服務
我們的共同目標，是協助您的使用者快速找到他們需要的內容，並更了解您的產品。我們會分享最佳實務，協助您建構出正確、完善的文件網站。
- 🎯 搜尋引擎最佳化友好
- 針對所有可能路徑，都會靜態產生 HTML 檔案。
- 頁面特定的搜尋引擎最佳化，協助您的使用者直接找到您的官方文件，進而解決他們目前遇到的問題。
- 📝 採用 MDX 的技術支援
- 透過 Markdown 中嵌入的 JSX 和 React，撰寫互動式組件。
- 在即時編輯器中分享您的程式碼，讓您的使用者當場就能愛上您的產品。
- 🔍 搜尋：您的完整網站都能搜尋。
- 💾 文件版本控制：讓文件的版本能與專案版本同步。
- 🌍 國際化 (i18n)：將您的網站翻譯成多國語言。
Docusaurus 2 的設計宗旨，就是讓它對您的所有使用者都容易親近且快速。
- ⚡️ 快速。Docusaurus 2 遵循 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 2 的許多面向都受到 Gatsby 最棒之處的啟發，而且是一個絕佳的替代方案。
Docz 是用於建立說明文件網站的 Gatsby 主題。它的功能目前少於 Docusaurus。
Next.js
Next.js 是另一個非常熱門的混合式 React 架構。它可以協助您建立良好的說明文件網站，但並沒有針對說明文件使用案例發表意見，而且需要更多的工作才能實作 Docusaurus 提供的現成功能。
Nextra 是建立在 Next.js 之上的見解式靜態網站產生器，它的功能目前少於 Docusaurus。
VuePress
VuePress 與 Docusaurus 有許多類似之處，兩者都極度重視以內容為中心的網站，並提供自訂化的文件功能。然而，VuePress 是以 Vue 為後盾，而 Docusaurus 是以 React 為後盾。如果你想要一個基於 Vue 的解決方案，VuePress 會是一個不錯的選擇。
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，因為可能有人已經在處理或它將成為我們路線圖的一部分。先與我們聯繫！