版本：3.5.2

版本控制

您可以使用版本控制命令列工具根據 docs 目錄中的最新內容建立一個新的說明文件版本。這特定組說明文件將會被保留，且即使 docs 目錄中的說明文件持續演進，您仍然可以存取。

警告

在開始對您的說明文件進行版本控制前三思，版本控制會讓貢獻者難以協助改善說明文件！

大多數時候，您不需要進行版本控制，因為版本控制只會增加建置時間，讓程式碼庫變得更複雜。版本控制最適合流量高、不同版本間說明文件變動頻繁的網站。如果您要說明的文件很少需要變更，請不要替說明文件加入版本控制。

若要更了解版本控制如何運作，並查看它是否符合您的需求， можете продовжити читати нижче.

概述

典型的版本控制文件網站如下所示

website
├── sidebars.json        # sidebar for the current docs version
├── docs                 # docs directory for the current docs version
│   ├── foo
│   │   └── bar.md       # https://mysite.com/docs/next/foo/bar
│   └── hello.md         # https://mysite.com/docs/next/hello
├── versions.json        # file to indicate what versions are available
├── versioned_docs
│   ├── version-1.1.0
│   │   ├── foo
│   │   │   └── bar.md   # https://mysite.com/docs/foo/bar
│   │   └── hello.md
│   └── version-1.0.0
│       ├── foo
│       │   └── bar.md   # https://mysite.com/docs/1.0.0/foo/bar
│       └── hello.md
├── versioned_sidebars
│   ├── version-1.1.0-sidebars.json
│   └── version-1.0.0-sidebars.json
├── docusaurus.config.js
└── package.json

versions.json 檔案是一個版本名稱清單，從最新順序到最舊。

下表說明如何將已版本控制的檔案對應到其版本和產生的 URL。

路徑	版本	網址
`versioned_docs/version-1.0.0/hello.md`	1.0.0	/docs/1.0.0/hello
`versioned_docs/version-1.1.0/hello.md`	1.1.0 (最新)	/docs/hello
`docs/hello.md`	當前	/docs/next/hello

提示

docs 目錄中的檔案屬於 current 文件版本。

預設情況下，current 文件版本標示為 Next 並置於 /docs/next/* 中，但是可以完全設定，以配合您的專案發布生命週期。

術語

請注意我們在此處使用的術語。

當前版本: 放置在 ./docs 資料夾中的版本。
最新版本/最後版本: 文件導覽列項目預設提供的版本。通常有路徑 /docs。

當前版本由檔案系統位置定義，而最新版本由導覽行為定義。它們可能為同一版本，也可能不是！（並且如上表所示的預設設定，會將它們視為不同版本：當前版本在 /docs/next，最新版本在 /docs。）

教學課程

標記新版本

首先，請確定目前的的文件版本（./docs 目錄）已準備好凍結。
輸入一組新版本號碼。

npm
Yarn
pnpm

npm run docusaurus docs:version 1.1.0

yarn docusaurus docs:version 1.1.0

pnpm run docusaurus docs:version 1.1.0

標記新版本時，文件版本控制機制將

將完整的 docs/ 資料夾內容複製到新的 versioned_docs/version-[versionName]/ 資料夾。
根據您目前側邊欄設定建立一個版本化的側邊欄檔案（如果存在） - 儲存為 versioned_sidebars/version-[versionName]-sidebars.json。
將新版本號碼加入 versions.json。

建立新文件

將新的檔案放置到對應的版本資料夾中。
根據版本編號在對應的側邊欄檔案中包含新的檔案的參考資料。

目前的版本架構
較舊的版本架構

# The new file.
docs/new.md

# Edit the corresponding sidebar file.
sidebars.js

# The new file.
versioned_docs/version-1.0.0/new.md

# Edit the corresponding sidebar file.
versioned_sidebars/version-1.0.0-sidebars.json

提示

經版本控制的側邊欄檔案與標準的側邊欄檔案類似，與特定版本的內容根目錄相關，因此根據上方的範例，您的經版本控制的側邊欄檔案可能如下所示

{
  "sidebar": [
    {
      "type": "autogenerated",
      "dirName": "."
    }
  ]
}

或對於手冊側邊欄

{
  "sidebar": [
    {
      "type": "doc",
      "id": "new",
      "label": "New"
    }
  ]
}

更新現有的版本

您可以同時更新多個文件的版本，因為versioned_docs/中的每個目錄在發佈時都代表特定的路由。

編輯任何檔案。
提交並推播變更。
它將會發佈到該版本。

範例：在versioned_docs/version-2.6/中變更任何檔案時，它只會影響版本2.6的說明文件。

刪除現有的版本

您也可以刪除/移除版本。

從versions.json中移除版本。

範例

[
  "2.0.0",
  "1.9.0",
- "1.8.0"
]

刪除經版本控制的說明文件目錄。範例：versioned_docs/version-1.8.0。
刪除經版本控制的側邊欄檔案。範例：versioned_sidebars/version-1.8.0-sidebars.json。

設定版本控制行為

「目前的」版本是./docs資料夾的版本名稱。有許多方式可以管理版本控制，但以下兩種是最常見的模式

您發佈 v1，並立即開始處理 v2（包含說明文件）。在這種情況下，目前的版本是 v2，它位於./docs原始碼資料夾中，可以在example.com/docs/next上瀏覽。最近的版本是 v1，它位於./versioned_docs/version-1原始碼資料夾中，並且大部分的使用者可以在example.com/docs上瀏覽。
您發佈 v1，並會在考慮 v2 之前維護它一段時間。在這種情況下，目前的版本和最近的版本都會指向 v1，因為 v2 的說明文件尚未存在！

Docusaurus 預設值非常適合第一種使用案例。我們會將目前的版本標示為「下一個」版本，您甚至可以選擇不發佈它。

對於第 2 種使用案例：如果您發佈 v1 且不打算在近期處理 v2，您可以將 v1 視為「自訂版本」，而不是建立 v1 的版本並在 2 個資料夾中維護說明文件（./docs + ./versioned_docs/version-1.0.0），您可以考慮透過提供路徑和標籤「假裝」目前的版本為自訂版本

docusaurus.config.js
export default {
  presets: [
    '@docusaurus/preset-classic',
    docs: {
      lastVersion: 'current',
      versions: {
        current: {
          label: '1.0.0',
          path: '1.0.0',
        },
      },
    },
  ],
};

./docs 中的文件將在 /docs/1.0.0 而不是 /docs/next 提供服務，並且 1.0.0 會變成導覽列下拉式選單中我們連結到的預設版本，而你只需要維護單一的 ./docs 資料夾。

我們提供這些外掛模組選項來自訂版本控制行為

disableVersioning：明確禁用版本控制，即使有版本。這會使網站只包含目前的版本。
includeCurrentVersion：包含文件的目前的版本（./docs 資料夾）。
- 提示：如果目前的版本是在進行中的工作，尚未準備好發布，請關閉它。
lastVersion：設定「最新版本」（/docs 路徑）指涉哪個版本。
- 提示：lastVersion: 'current' 在你的目前的版本指涉不斷修正和發布的主要版本時才有意義。最新版本的實際路徑基礎路徑和標籤都可設定。
onlyIncludeVersions：定義從 versions.json 要部署的版本的子集。
- 提示：在開發中和部署預覽中限制為 2 或 3 個版本以改善啟動和建置時間。
versions：版本中繼資料的字典。對於每個版本，你可以自訂下列內容
- label：在版本下拉式選單和橫幅中顯示的標籤。
- path：此版本的路徑基礎路徑。預設上，最新版本為 /，而目前版本為 /next。
- banner：'none'、'unreleased' 和 'unmaintained' 其中之一。決定在每一個文件頁面頂端顯示什麼。任何高於最新版本以上的版本都會是「未發布」，而任何低於版本都會是「缺乏維護」。
- badge：在該版本的文件的頂端顯示一個有版本名稱的徽章。
- className：加入一個自訂的 className 至該版本的文章頁面的 <html> 元素中。

請參閱文件外掛模組設定以取得更多詳情。

我們提供幾個導覽列項目，幫助你快速設定導覽，不用擔心版本化路徑。

doc：連結到一個文件。
docSidebar：連結到側邊欄中的第一個項目。
docsVersion：連結到目前檢視版本的主文件。
docsVersionDropdown：下拉式清單，包含所有可用的版本。

這些連結都會尋找適當的版本連結，順序如下

活動版本：如果使用者目前正在瀏覽由這個文件外掛模組提供的頁面，則為使用者目前正在瀏覽的版本。如果他不在文件頁面，則會復歸到...
偏好的版本：使用者最後查看的版本。如果沒有記錄，則退回到...
最新版本：我們導覽到的預設版本，是透過 lastVersion 選項設定。

建議做法

只在有需要時修改文件的版本

例如，您正在為 npm 套件 foo 建立文件，您目前處於 1.0.0 版本。隨後，您釋出一個修補程式版本來修正一個小錯誤，現在為 1.0.1。

您是否要削減一個新的 1.0.1 文件版本？您可能不應這麼做。根據 semver，1.0.1 和 1.0.0 文檔不應有所不同，因為沒有新功能！削減一個新版本只會無故建立重覆的文件。

讓版本數量保持較小

作為一個好的經驗法則，請嘗試讓您的版本數量保持在 10 以下。您很有可能會有很多已過時且無人閱讀的舊版本文件。例如，Jest 目前為 27.4 版本，並且僅保留幾個最新文件版本，最低為 25.X。讓它保持較小😊

封存較舊版本

如果您在 Jamstack 供應商 (例如 Netlify) 上佈署您的網站，供應商會將每個成品建置存成一個快照，放入一個不可變的 URL 中。您可以將永遠不會被重新建置的封存版本當成這些不可變 URL 的外部連結。Jest 網站和 Docusaurus 網站都使用此模式，讓主動建置的版本數量保持在較低。

在文件內部使用絕對路徑導入

請勿在文件中使用相對路徑導入。因為當我們削減一個版本時，路徑就不再起作用 (巢狀層級不同，以及其他原因)。您可以利用 Docusaurus 提供的指向 website 目錄的 @site 別名。範例

- import Foo from '../src/components/Foo';
+ import Foo from '@site/src/components/Foo';

藉由檔案路徑連結文件

使用副檔名為 .md 的相對檔案路徑參考其他文件，如此一來，Docusaurus 便可在建置期間將其改寫為實際的 URL 路徑。檔案將連結到正確的對應版本。

The [@hello](hello.mdx#paginate) document is great!

See the [Tutorial](../getting-started/tutorial.mdx) for more info.

全域性或依版本而異的並置資源

您應決定像圖片和檔案這類的資源是屬於個別版本或在各版本間共享使用。

如果您的資源應依版本處理，請將它們放置在文件版本中，並使用相對路徑

![img alt](./myImage.png)

[download this file](./file.pdf)

如果您的資源是全域性的，請將它們放置在 /static 中，並使用絕對路徑

![img alt](/myImage.png)

[download this file](/file.pdf)

概述​

術語​

教學課程​

標記新版本​

建立新文件​

更新現有的版本​

刪除現有的版本​

設定版本控制行為​

導覽列項目​

建議做法​

只在有需要時修改文件的版本​

讓版本數量保持較小​

在文件內部使用絕對路徑導入​

藉由檔案路徑連結文件​

全域性或依版本而異的並置資源​

概述

術語