Facebook Docusaurus 中文文檔 版本化

此係列文章的應用示例已發佈於 GitHub: docusaurus-docs-Zh_CN. 能夠 Fork 幫助改進或 Star 關注更新. 歡迎 Star.

版本化

您可使用 version 腳本根據 docs 文件夾中的最新內容來剪切新的文檔版本。 即便 docs 文件夾中的文檔發生變化，該特定的文檔集也將保留並可訪問。

如何建立新版本

運行如下腳本以生成並列出全部網站版本的初始版本頁面：

yarn examples versions

這將建立如下文件：

pages/en/versions.js

您稍後能夠編輯此文件以自定義如何顯示版本。

若是腳本不存在，請將如下腳本添加到 package.json 文件中：

...
"scripts": {
  "version": "docusaurus-version"
},
...

用您但願建立的版本的命令行參數運行腳本。 例如：

yarn run version 1.0.0

這將保留當前在 docs 文件夾中的全部文檔，並使它們做爲版本 1.0.0 的文檔提供。

例如，若是您使用1.0.0做爲版本號運行版本腳本，則版本1.0.0將被視爲您項目的最新版本。 該站點將顯示標題旁標題的版本號。 此版本號連接到您以前建立的版本頁面。

docs 文件夾中的文檔將被認爲是 next 版本的一部分，並使它們可用。例如在 URL docs/next/doc1.html 處，最新版本的文檔使用 url docs/doc1.html。

用 yarn run version 2.0.0 再次運行腳本將會建立一個 2.0.0 版本，使得2.0.0版本成爲最新版本的文檔。 來自1.0.0版本的文檔將使用 URL docs/1.0.0/doc1.html，而 2.0.0 將使用 docs/doc1.html。

版本化模式

您能夠以任何您想要的格式建立版本號，只要與現有版本不匹配，就可使用任何版本號建立新版本。 版本排序由建立版本的順序決定，與編號的方式無關。

存儲每一個版本的文件

版本化的文檔被放置在 website/versioned_docs/version-${version} 中，其中 ${version} 是你提供 version 腳本的版本號。

每一個版本化文檔的 markdown 標題都會經過將 id frontmatter 字段重命名爲 original_id，而後使用 "version-${version}-${original_id}" 做爲實際的 id 字段的值來更改。

版本化的邊欄被複制到 website/versioned_sidebars 中，並被命名爲 version-${version}-sidebars.json。

一個 website/versions.json 文件是在您第一次剪切版本時建立的，並被 Docusaurus 用來檢測存在的版本。 每次添加新版本時，都會將其添加到 versions.json 文件中。

若是您但願更改之前版本的文檔，則能夠訪問相應版本的文件。

回退功能

每次指定新版本時，只有 docs 文件夾和側邊欄文件中與最新版本文件不一樣的文件纔會被複制。 若是版本之間沒有變化，Docusaurus 將使用該文件的最新版本的文件。

例如，具備原始 id doc1 的文檔存在於最新版本 1.0.0 中，而且具備與 docs 文件夾中具備id doc1 的文檔相同的內容。 當建立一個新版本 2.0.0 時，doc1 文件不會被複制到 versioned_docs/version-2.0.0/ 中。 仍然會有一個 docs/2.0.0/doc1.html 的頁面，但它將使用版本爲 1.0.0 的文件。

重命名現有版本

要將現有版本號重命名爲其餘內容，請首先確保如下腳本位於 package.json 文件中：

...
"scripts": {
  "rename-version": "docusaurus-rename-version"
},
...

使用命令行參數運行腳本，當前版本名稱，而後是新版本名稱。 例如：

yarn run rename-version 1.0.0 1.0.1

版本化和翻譯

若是你想使用版本化和翻譯功能，應該設置 crowdin.yaml 文件來上傳和下載來自 Crowdin 的版本化文檔以進行翻譯。 翻譯後的版本化文件將進入文件夾translated_docs/${language}/version-${version}/。 有關更多信息，請查看翻譯指南。

若是這篇文章對您有幫助, 感謝 下方點贊 或 Star GitHub: docusaurus-docs-Zh_CN 支持, 謝謝.