版本化站点

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

迁移你的 versioned_docs 前置内容​

与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 前置内容不再更改，将保持不变。在内部，它被设置为 version-${version}/${id}。

基本上，以下是每个版本化文档文件中必要的更改：

---
- 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:

{
+ "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>