宣布 Docusaurus 2.0

今天我們非常高興終於能 宣布 Docusaurus 2.0！ 🥳️

在 Meta 開源，我們相信 Docusaurus 將幫助你以 最小努力建立 最佳的說明文件網站，讓你 專注於真正重要的部分：編寫內容。

經過 4 年的工作，75 个 Alpha 版 和 22 个 Beta 版，下一代 Docusaurus 已準備進入成熟階段。從現在開始，我們計劃遵循 语义化版本控制 並將更频繁地发布主要版本。

我們已在 ProductHunt 和 Hacker News 上！

現在是表達您對 Docusaurus 熱愛之情的最佳時機！

Docusaurus 到底是什么？​

Docusaurus 是一款静态网站生成器，可帮助您在短时间内发布美观的文档网站。

关注您的内容：只需编写Markdown 文件即可。Docusaurus 将为您生成一个经过优化的网站，该网站可轻松托管在任何位置。

Docusaurus 功能齐全且非常灵活：我们随附精心设计的文档和博客版面，以及开箱即用的版本控制、搜索和国际化功能，以及可访问性和搜索引擎优化呼吁。其灵活的主题化系统允许调整 UI 以匹配您的品牌，以便与您的主网站或文档门户很好地集成。它使用React 使客户端导航现代化，并能够构建交互式文档。

Docusaurus 理念类似于帕累托原则：您能用20% 的精力获得80% 的成果。这使您能够以最小的精力与一流的文档网站竞争。

Docusaurus 的目的是成為最佳文件編寫工具，但您也可以用於其他用途：網誌、知識庫、開發人員作品集、第二大腦，甚至用來架設登陸頁面！

Docusaurus 背後的故事​

Docusaurus 由Facebook 開源社群於2017 年 (現為Meta 開源社群) 創建。我們有許多內部及開源專案需要撰寫文件。撰寫完善文件已經夠複雜，更別提還要建立HTML、CSS、和適用於美觀網站的 JavaScript。我們希望專案負責人能夠專注於內容，而Markdown正是理想的選擇。

當時，我們的解決方案是反覆複製/貼上 Jekyll 範本。這當然會難以維護，因此我們建立了一項工具，一次解決我們自己的痛點。

Docusaurus v1 誕生了!

它快速地在 Facebook 及前端生態系統中受到關注，並被許多熱門專案採用，例如 Prettier、Babel、React-Native、KaTeX，當然還有Docusaurus v1 本身。

邁向 Docusaurus 2.0​

Docusaurus v1非常成功，但我們開始質疑某些架構選擇

• React 僅作為伺服器端範本語言，並未在客戶端使用
• 佈景主題系統非常有限，除了可以使用 CSS 變更少數顏色之外，難以進行更進階自訂
• 文件版本控制系統難以理解，因為它是建立在 diff 演算法上
• 程式碼庫一體成型，測試不周延而且難以擴充

Docusaurus v2 從頭開始重新打造，採用新的模組化架構

• 現在也使用 React 在客戶端，這使現代化單頁面應用程式導覽成為可能
• 外掛程式讓社群能夠以第三方套件的方式提供實用的功能
• 佈景主題比以往更靈活
• 文件版本控制現在使用快照複本，易於理解
• 我們保留了v1 中所有優點：文件、博客、頁面、版本控制、i18n...
• 我們實作了多項新功能

Docusaurus 2 專案公告 和 v1 到 v2 的移轉指南 中有更詳細的資訊

誰在使用 Docusaurus 2.0？​

儘管仍在預先發布階段，但未花費多長時間，Docusaurus v2 就已在 NPM 下載方面超越 Docusaurus v1

我們的 GitHub 星象趨勢非常正向，與主要的架構相抗衡

Docusaurus v2 即使在發布前，就已經是一大成功

• 我們收到許多 美好的見證
• 1Password 和 Courier 都撰寫了他們正面的使用者體驗
• 我們的 網站展示 參考了數百個網站，而且這只是冰山一角。

2.0 有什麼新功能？​

如果要描述 Docusaurus v2 的每項新功能，可能會有點困難。讓我們先關注我們認為影響最重大的功能。

MDX​

MDX 讓你可以穿插 Markdown 的 React元件。這能讓你非常輕鬆建構最棒的互動式文件體驗。

示範能勝過千言萬語

### Give it a try: press that button!

import ColorModeToggle from '@theme/ColorModeToggle';

<ColorModeToggle/>

檔案系統公約​

我們的目標是讓非常直覺地使用 Docusaurus。我們加入了檔案系統公約，輕鬆建立文件頁面，就像建立一個 Markdown 檔案一樣簡單。

外掛程式​

Docusaurus 現在搭配外掛程式系統，擁有一個模組化架構，我們的核心功能，例如文件、部落格、頁面和搜尋，全部由個別外掛程式支援。

更重要的是，它讓社群能以額外的功能強化 Docusaurus。

讓我們突顯一些範例

• redocusaurus：與OpenAPI 和Redoc 完美整合

• docusaurus-preset-shiki-twoslash：使用 Shiki 程式碼區塊語法突顯與 TwoSlash TypeScript 編譯器提示

• docusaurus-search-local：內建 Algolia 外掛程式的各種在地搜尋替代方案之一

主題調整​

主題調整是 Docusaurus 最重要的功能之一：我們認為一份專業的文件網站應當尊重貴公司的品牌並建立一致的體驗。

Docusaurus 主題調整在許多層級上提供了大量的彈性

• 自訂 CSS 變數以調整顏色、字型等等
• 提供您自己的 CSS 樣式表
• 從頭開始實作您自己的主題
• 覆寫任何 React 元件，由我們的預設主題提供：我們稱之為 切換

這讓願意花更多時間在自訂上的使用者得以建立外觀截然不同於他人的網站。

其他功能​

Docusaurus 2 附帶了許多有用的功能

• 主題：黑暗模式、更棒的 UI 和 UX、彈性的 themeConfig 選項...
• 文件版本控制：彈性的外掛程式選項，能適應您的工作流程
• 文件側邊欄：可摺疊類別、類別索引頁面...
• 部落格：多位作者、作者地圖、檔案頁面...
• Markdown：分頁、數學方程式、即時程式區段、連結、彈性的開場白...
• 搜尋：使用新的 Algolia DocSearch 3 體驗
• 素材：輕鬆加入圖片和其他類型的檔案
• 國際化：設定選項、主題的預設翻譯...
• 易於存取：aria 標籤、顏色對比、跳到內容、鍵盤導覽、漸進式加強...
• SEO：合理預設值、易於自訂、唯一定址網址、社交卡片、no-index、網站地圖、微資料、hreflang...
• PWA：為你的網站增加離線支援，並讓其可安裝
• 快速失效：嚴格的設定驗證，偵測斷裂連結並防止不當的生產環境部署
• TypeScript 支援設定檔、外掛程式、自訂頁面和主題作者
• 遊樂場：使用 docusaurus.new 從你的瀏覽器輕鬆評估 Docusaurus
• Canary 版本：使用 @canary npm 標籤，比其他人更早使用即將推出的版本
• 測試：Docusaurus 經過良好測試，我們採用狗糧策略，確保它們持續運作

為什麼是現在的 2.0 版本？​

許多年來，我們的熱情追隨者一直很好奇為何我們花了 4 年的時間才發行 Docusaurus 2.0 版本，即便 beta 版已十分成功，而且廣泛用於生產環境中。

原因在於，我們的目標是遵守 語意化版本管理，這表示只要我們發行任何重大變更，就會增加主要版本編號。

這麼做有以下多個原因

• 只要你只使用 公開 API，就能保證輕鬆升級次要版本
• 遵循前端生態系統公約
• 新的主要版本是徹底記錄重大變更的機會
• 新的主要/次要版本是透過網誌文章傳達新功能的機會

問題在於，我們的彈性佈景主題系統本身就建立了非常隱含的 API 表面，這使得一開始很難知道什麼是重大變更。高度自訂化的 Docusaurus 站點有時很難升級 Docusaurus，因為它們使用內部 API 來執行自訂化。我們花時間對佈景主題進行廣泛重構，並清楚地定義我們的 公開 API，以便未來可以更安全地進行程式碼變更。我們將持續擴展這個公開佈景主題 API，以便最常見的站點自訂化不需要使用任何內部 API。

下一步？​

Docusaurus 3.0 的開發工作已經開始，而下一個版本將在幾個月內發佈。我們將逆向移植 Docusaurus 2.x 的向下相容變更到次要版本中，以盡快透過穩定頻道提供給社群。

Docusaurus 即將到來的主要版本中，我們路線圖上的功能範例：

• 升級至 MDX 2.0
• 改善 Markdown 基礎架構
• 改善佈景主題和 swizzle
• TailwindCSS 佈景主題
• 佈景主題：支援 navbar、文件側邊欄、網誌側邊欄、頁腳的自訂項目類型
• 動態 navbar：navbar 項目啟用策略
• 自訂 Social Card
• 支援 CSS-in-JS
• 使用 Node.js ES Modules
• 改善建置時間效能
• 擴充 Docusaurus 外掛程式、CMS 整合

感謝您​

我們要感謝所有貢獻者，包括：

• Docusaurus 核心團隊：Alexey Pyltsyn、Joshua Chen、Sébastien Lorber、Yangshun Tay，以及我們的所有前任團隊成員
• Joel Marcey，因建立 Docusaurus 1.0 並在 Meta Open Source 支援 Docusaurus 2.0 專案
• Paul O’Shannessy，因在 Meta Open Source 支援所有後續版本 Docusaurus 的開發
• Eric Nakagawa，因創造出我們最可愛的吉祥物 Slash
• Endilie Yacop Sucipto，因其在 Docusaurus v2 的早期重大工作
• Clément Vannicatte、Kevin Granger 及整個 Algolia 團隊，因其支援
• 所有社群成員，因其在程式碼、文件改善和Discord 上回答問題方面做出有價值的貢獻

我們特別感謝所有早早採用 Docusaurus 2.0 的人，他們評估其 alpha、beta 和 canary 版本，提供了許多寶貴的回饋。我們誠摯地希望您在使用它時有美好的體驗，今後可繼續提供有關 Docusaurus 3.0 即將發布的預覽版本的回饋。

在 Meta 開源，Docusaurus 我們最成功的專案之一。我們迫不及待想看到您將建立的出色文件網站！請別忘了將它們提交給我們的 網站展示！

現在，盡情發揮您的想像力吧 🤪！

— Slash

我們已在 ProductHunt 和 Hacker News 上！

🙏 與社群分享您使用 Docusaurus 的經驗吧！