跳到主要内容

版本化站点

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

备注

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

迁移您的 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}。

本质上，以下是每个 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：

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（同时使用正确的前置内容和 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>
最后于 更新