版本化站点

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

注意

版本化的文档通常会通过 迁移 CLI 正确迁移。

迁移您的 versioned_docs 前端 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 前端 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 中，很有可能有人创建了一个新的文件，其前端 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 中使用 / 作为前端 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）。

例如，如果您的 versions.json 在 v1 中如下所示

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（以及正确的前端 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>