版本化站点

请先阅读 https://docusaurus.org.cn/blog/2018/09/11/Towards-Docusaurus-2#versioning 了解 v1 方法中存在的问题。

注意

版本化的文档通常应该通过迁移 CLI正确迁移

迁移你的 versioned_docs front matter

与 v1 不同，每个版本化文档的 Markdown 头部不再通过使用 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 front matter 不再被修改，并将保持不变。在内部，它被设置为 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 中，很可能有人创建了一个新的文件，其 front matter 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 的 front matter 中使用 /，因此发生冲突的可能性较小。

所以 v1 用户需要迁移他们的 versioned_sidebars 文件

示例 versioned_sidebars/version-1.0.0-sidebars.json

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），这在以前的版本中是不可能的。

例如，如果你的 v1 中的 versions.json 看起来像这样

versions.json

["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（并且带有正确的 front matter 和 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>