版本化網站
請先閱讀 https://docusaurus.dev.org.tw/blog/2018/09/11/Towards-Docusaurus-2#versioning 以了解 v1 方法的問題。
版本化文件通常應可由 遷移 CLI 正確遷移
遷移 versioned_docs 前置事項
與 v1 不同，每個版本化文件的標題不再使用 `version-${version}-${original_id}` 作為實際 ID 欄位的數值。請參閱下面的範例以取得更深入的說明。
例如，如果你有一個 `docs/hello.md`。
---
id: hello
title: Hello, World !
---
Hi, Endilie here :)
在你剪下一個新的版本 1.0.0 時，在 Docusaurus v1 中，`website/versioned_docs/version-1.0.0/hello.md` 看起來像這樣
---
id: version-1.0.0-hello
title: Hello, World !
original_id: hello
---
Hi, Endilie here :)
相比之下，Docusaurus 2 中的 `website/versioned_docs/version-1.0.0/hello.md` 看起來像這樣 (與原始文件完全相同)
---
id: hello
title: Hello, World !
---
Hi, Endilie here :)
由於我們要取得快照，同時允許人們在版本中輕鬆移動 (並編輯) 文件，因此 `id` 原文書不再變更並將保持不變。在內部，它會被設定為 `version-${version}/${id}`。
基本上，以下是每個 versioned_docs 檔案中必要的變更
---
- id: version-1.0.0-hello
+ id: hello
title: Hello, World !
- original_id: hello
---
Hi, Endilie here :)
移轉你的 `versioned_sidebars`
- 參考 `versioned_docs` ID 為 `version-${version}/${id}` (v2) 而非 `version-${version}-${original_id}` (v1)。
因為在 v1 中，很有可能有人建立一個原文書 ID 為 `"version-${version}-${id}"` 的新檔案，這可能會與 `versioned_docs` ID 發生衝突。
例如，Docusaurus 1 無法區分 `docs/xxx.md`
---
id: version-1.0.0-hello
---
Another content
與 `website/versioned_docs/version-1.0.0/hello.md`
---
id: version-1.0.0-hello
title: Hello, World !
original_id: hello
---
Hi, Endilie here :)
由於我們在 v1 和 v2 中不允許原文書中有 `\`，因此發生衝突的可能性較小。
所以 v1 使用者需要移轉他們的 versioned_sidebars 檔案
範例︰`versioned_sidebars/version-1.0.0-sidebars.json`
{
+ "version-1.0.0/docs": {
- "version-1.0.0-docs": {
"Test": [
+ "version-1.0.0/foo/bar",
- "version-1.0.0-foo/bar",
],
"Guides": [
+ "version-1.0.0/hello",
- "version-1.0.0-hello"
]
}
}
填入你的 `versioned_sidebars` 和 `versioned_docs`
在 v2 中，我們對文件版本控管使用快照方法。每個版本化的文件都不依賴於其他版本。有可能在 `version-1.0.0` 中有 `foo.md` 但在 `version-1.2.0` 中沒有。由於 Docusaurus v1 的備用功能，在先前的版本中這是辦不到的 (https://v1.docusaurus.io/docs/en/versioning#fallback-functionality).
例如，如果你的 `versions.json` 在 v1 中看起來像這樣
["1.1.0", "1.0.0"]
Docusaurus v1 僅當文件內容不同時才會建立版本化文件。如果 v1.0.0 和 v1.1.0 唯一變更的文件是 `hello.md`，你的文件結構可能看起來像這樣。
website
├── versioned_docs
│ ├── version-1.1.0
│ │ └── hello.md
│ └── version-1.0.0
│ ├── foo
│ │ └── bar.md
│ └── hello.md
├── versioned_sidebars
│ └── version-1.0.0-sidebars.json
在 v2 中，你必須填入遺失的 `versioned_docs` 和 `versioned_sidebars` (也包含正確的原文書和 ID 參考)。
website
├── versioned_docs
│ ├── version-1.1.0
│ │ ├── foo
│ │ │ └── bar.md
│ │ └── hello.md
│ └── version-1.0.0
│ ├── foo
│ │ └── bar.md
│ └── hello.md
├── versioned_sidebars
│ ├── version-1.1.0-sidebars.json
│ └── version-1.0.0-sidebars.json
將 MDX 中的樣式屬性轉換為樣式物件
Docusaurus 2 為文件使用 JSX。如果你在你的 Docusaurus 1 文件中有任何樣式屬性，請將它們轉換為樣式物件，像這樣
---
id: demo
title: Demo
---
## Section
hello world
- pre style="background: black">zzz</pre>
+ pre style={{background: 'black'}}>zzz</pre>