版本化站点

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

备注

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

迁移您的 versioned_docs 前置内容

与 v1 不同，不再通过使用 version-${version}-${original_id} 作为实际 ID 字段的值来更改每个版本化文档的 Markdown 头。请参见下面的场景以更好地解释。

例如，如果您有 docs/hello.md。

---
id: hello
title: Hello, World !
---

Hi, Endilie here :)

在 Docusaurus v1 中，当您剪切新的 1.0.0 版本时，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 中不允许在 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)，这在之前的版本中是不可能的。

例如，如果您的 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（以及正确的 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>