走向 Docusaurus 2
Docusaurus 於九個月前已 正式宣佈 推出，是開發開源文件網站的簡便方式。自此之後，已累計超過 8,600 個 GitHub 星星，並廣泛使用於許多熱門開源專案中，例如 React Native、Babel、Jest、Reason 和 Prettier。
俗話說，最好的軟體持續演進，最差的軟體絲毫不動。如果您尚未得知，我們一直在規劃和開發下一代 Docusaurus 🎉。
简介
一切都始於 這篇 RFC 問題，於 2018 年 6 月底由 Yangshun 開啟。
[RFC] Docusaurus v2 · Issue #789 · facebook/docusaurus
以下是目前我在 Docusaurus 發現的一些問題，以及在 v2 中我們如何解決這些問題。這裡有許多想法都受到 VuePress 和其他靜態網站產生器的啟發。在目前的靜態網站產生器生態系統中，t...
建議的改進事項大部分已在問題中提及，我將提供一些關於 Docusaurus 1 問題的詳細說明，以及我們如何在 Docusaurus 2 中解決這些問題。
基礎架構
內容
其實，Docusaurus 1 網站會建置在許多靜態 HTML 頁面中。即使使用 React，我們也並未充分利用 React 提供的功能，例如元件狀態，而此功能可以建立動態且互動式的頁面。React 僅被用作靜態內容的樣板引擎，而互動性必須透過腳本標籤和 dangerouslySetInnerHTML 加以新增，真令人擔心！
此外，目前沒有簡單的方式可以變更 Docusaurus 載入內容的方式。例如，原生不支援新增像 Sass 和 Less 等 CSS 預處理器，且需要使用許多使用者自行修改的腳本。
對於 Docusaurus 2，我們會使用 webpack 作為模組打包器，且我們會變更提供內容的方式。新增 CSS 預處理器會如同新增 webpack loader 一樣簡單。我們會在建置時產生一個應用程式的伺服器呈現版本，並呈現相應的 HTML，而不是純靜態 HTML。Docusaurus 網站基本上會是一個同構/通用應用程式。此方法很大地受到 Gatsby 所啟發。
版本控制
如果你已經使用 Docusaurus 一段時間，你可能會注意到 Docusaurus 只會在文件內容不同時建立經過版本控制的文件。
例如，如果我們有 docs/hello.md
---
id: hello
title: hello
---
Hello world !
我們建立版本 1.0.0 之後，Docusaurus 會建立 versioned_docs/version-1.0.0/hello.md
---
id: version-1.0.0-hello
title: hello
original_id: hello
---
Hello world !
不過，如果在建立 v2.0.0 時 hello.md 沒有變更，Docusaurus 就會不為此文件建立經過版本控制的文件。換句話說，versioned_docs/version-2.0.0/hello.md 將不會存在。
這對於使用者來說可能是很混淆的，如果他們想要編輯 v2.0.0 文件，那麼他們必須編輯 versioned_docs/version-1.0.0/hello.md 或是手動新增 versioned_docs/version-2.0.0/hello.md。這可能會潛在地導致不想要的錯誤。以下是一個 Jest 中的真實場景。
此外，這增加了代碼庫的複雜度，因為我們需要一個版本回溯機制。而在建置期間，Docusaurus 必須替換對正確版本的連結。這也是一個錯誤的原因， 變更文件的檔名會中斷舊版本中的連結。
對於 Docusaurus 2，每當我們建立一個新版本時，反而會拍攝所有文件的快照。我們不需要文件內容進行變更。對於更好的開發人員和使用者體驗來說，這是一種空間複雜性考量。我們將使用更多的空間來獲得更好的關注點分離和保證正確性。
翻譯
Docusaurus 允許使用 Crowdin，來輕鬆進行翻譯功能。以英文寫成的文件上傳到 Crowdin，讓社群中的使用者來翻譯。我們總是假設英文是預設語言，但這可能並非適用於所有使用者。我們已看過許多非英文的開源專案使用 Docusaurus。
對於 Docusaurus 2，我們不會假設英文是預設語言。當使用者啟用國際化時，他們必須在 siteConfig.js 中設定一個預設語言。我們隨後會假設 docs 中的所有檔案都是以該語言寫成。
此外，在處理 Docusaurus 2 的 MVP 之後，我發現不用 Crowdin 也可以進行翻譯。因此，我們可能需要新增一個額外工作流程來啟用那個場景。不過，我們仍然強烈建議人們使用 Crowdin 以利於整合。
可自訂性
版面
Docusaurus 目前的狀態是負責整個版面和樣式設定，無意間讓使用者很難自訂其網站的外觀。
對於 Docusaurus 2，佈局和樣式應由使用者控制。Docusaurus 會處理內容產生、路由、翻譯和版本控制。Docusaurus 受到 create-react-app 和 VuePress 的啟發，它仍會提供預設佈景主題，使用者可以從中彈出，以進一步自訂佈局和樣式。這表示使用者可以使用 React Helmet 甚至變更 HTML meta。以社群為基礎的佈景主題也是非常有可能的。允許使用者負責佈局和樣式的此方法是由大多數靜態網站產生器採用的。
Markdown
我們的 Markdown 剖析目前由 Remarkable 的支援。如果使用者想要使用 Markdown-it 甚至 MDX 呢？然後還有哪個語法突顯器應該使用（例如：Prism 與 Highlight.js）。我們應該讓使用者選擇這些選項。
對於 Docusaurus 2，使用者可以彈出並選擇自己的 Markdown 剖析器。如果他們想要使用另一個 Markdown 剖析器（例如 Remark）甚至自己的內部 Markdown 剖析器，這並不重要。根據經驗法則，使用者必須提供一個 React 元件，我們將提供包含 Markdown RAW 字串的子項屬性。預設情況下，我們會使用 Remarkable 作為 Markdown 剖析器並使用 Highlight.js 作為語法突顯。預設剖析器仍有可能在將來變更，因為我們仍在嘗試不同的 Markdown 剖析器。
搜尋
我們的核心搜尋功能是根據 Algolia。有一些使用者要求能夠使用不同的搜尋服務，例如用於離線搜尋的 lunrjs。
我個人喜歡 Algolia，我們與他們合作有很好的經驗。他們反應非常迅速；由於其 DocSearch 是開放原始碼的，所以我們可以輕鬆提交一個拉取請求給 Algolia。例如，我最近提交了 此 PR，使 DocSearch 能在網站地圖中抓取交替語言。
對於 Docusaurus 2，我們將允許使用者自訂搜尋方塊。使用者只需退出預設主題並修改搜尋 UI（一個 React 元件）即可。不過，我們仍會在預設主題中使用 Algolia。
穩定性
軟體永遠不可能完美，但我們希望能讓 Docusaurus 在我們新增新功能的同時不會中斷。Docusaurus 初次發布時，沒有任何強大的自動測試套件。因此，有很多回歸未即時發現。雖然我們最近已新增許多測試，但測試覆蓋率仍然相對較低。
對於 Docusaurus 2，我們在開發的同時加入測試，因為我們打算重新編寫。因此，我相信它應該會比以往更穩定，而且與 Docusaurus 1 相比，應該更難中斷。
常見問題
會有破壞性變更嗎？
如果你已閱讀此篇文章直到這裡，你應該會注意到會有破壞性變更。雖然我們會盡可能將破壞性變更的數量降至最低並盡量保持向後相容性，但我們認為有些破壞性變更是必要的。這主要是因為 Docusaurus 2 對程式碼庫進行了重大重新編寫和重新建構。
破壞性變更的完整清單尚未完全確定，因為開發尚未確定完成。不過，我要強調的是，我們會停止支援 siteConfig.js 中許多選項，並打算盡可能保持精簡。例如，cleanUrl siteConfig 將停止支援，因為 Docusaurus 2 網站的所有 URL 都將沒有 .html 字尾。
我們的目標是，大多數網站都能順利升級到 Docusaurus 2，不會有太多困擾。我們也會在發布 Docusaurus 2 時一同附上遷移指南。到了那個時候，請隨時上 Discord 或 Twitter 提出問題並尋求協助。
Docusaurus 2 什麼時候會發布？
到目前為止，我們尚未規劃出確切的發布日期。我個人估計，我們或許能在未來一到兩個月內發布 Alpha 版，但這當然只是一個預估。
我想分享的是，雖然 Docusaurus 是 Facebook 開放原始碼 計畫的一部分，且團隊中的大多數成員都是 Facebook 員工，但維護及開發工作主要是在正常工作時間之外完成的。我目前是 新加坡國立大學 的大四學生，因此我必須在課業、畢業專題以及維護/開發 Docusaurus 之間取得平衡。不過，這並不表示我們不想讓 Docusaurus 變得更好。事實上，我們想要讓它盡可能地棒。
目前，實際的 Docusaurus 2 工作仍有一個私人存放庫。在不久的將來，我們會將它們移至 公開存放庫。屆時，我鼓勵每個人看看，並希望能以某種方式做出貢獻。在此之前，敬請期待 😉！
最後的想法
從 許多使用 Docusaurus 來撰寫文件 的熱門計畫中可以看到，Docusaurus 對開放原始碼社群具有很大的影響力。為了未來能夠更快速的推進，我們會利用這個機會來修復 Docusaurus 1 的一些核心問題，並努力讓 Docusaurus 對每個人來說都更好。事實上，可以很肯定地說 Docusaurus 2 不只是一項計畫而已；相關工作已經開始，希望我們可以在不久的將來看到它實現。
Docusaurus 的願景一直都是讓你輕輕鬆鬆就能建立一個具有文件功能的網站。這個願景不會隨著 Docusaurus 2 而改變。
我們也希望讓大家知道，因為我們正在開發 Docusaurus 2，我們不太會接受針對 Docusaurus 1 的新功能/重大變更。
如果你有使用 Docusaurus，你就是我們社群的一份子；請持續告訴我們如何才能讓 Docusaurus 對你來說更好。如果你很欣賞我們所做的工作，你可以透過 Open Collective 來支持 Docusaurus。
如果你在 Open Collective 上贊助我們的計畫，我們會親自為你在 Docusaurus 網站的維護和升級方面提供協助。