版本化网站

¥Versioned sites

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

¥Read up https://docusaurus.nodejs.cn/blog/2018/09/11/Towards-Docusaurus-2#versioning first for problems in v1's approach.

注意

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

¥The versioned docs should normally be migrated correctly by the migration CLI

迁移你的 versioned_docs 前端内容

¥Migrate your versioned_docs front matter

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

¥Unlike v1, The Markdown header for each versioned doc is no longer altered by using version-${version}-${original_id} as the value for the actual ID field. See scenario below for better explanation.

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

¥For example, if you have a 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 看起来像这样：

¥When you cut a new version 1.0.0, in Docusaurus v1, website/versioned_docs/version-1.0.0/hello.md looks like this:

---
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 看起来像这样（与原始版本完全相同）

¥In comparison, Docusaurus 2 website/versioned_docs/version-1.0.0/hello.md looks like this (exactly same as original)

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

Hi, Endilie here :)

因为我们要使用快照并允许人们在版本内轻松移动（和编辑）文档。id 的正面内容不再改变，将保持不变。在内部，它被设置为 version-${version}/${id}。

¥Since we're going for snapshot and allow people to move (and edit) docs easily inside version. The id front matter is no longer altered and will remain the same. Internally, it is set as version-${version}/${id}.

本质上，以下是每个 versioned_docs 文件中的必要更改：

¥Essentially, here are the necessary changes in each versioned_docs file:

---
- id: version-1.0.0-hello
+ id: hello
title: Hello, World !
- original_id: hello
---
Hi, Endilie here :)

迁移你的 versioned_sidebars

¥Migrate your versioned_sidebars

• 将 versioned_docs ID 称为 version-${version}/${id} (v2)，而不是 version-${version}-${original_id} (v1)。

  ¥Refer to versioned_docs ID as version-${version}/${id} (v2) instead of version-${version}-${original_id} (v1).

因为在 v1 中，很有可能有人创建了一个标题 ID 为 "version-${version}-${id}" 的新文件，该文件可能与 versioned_docs ID 冲突。

¥Because in v1 there is a good chance someone created a new file with front matter ID "version-${version}-${id}" that can conflict with versioned_docs ID.

例如，Docusaurus 1 无法区分 docs/xxx.md

¥For example, Docusaurus 1 can't differentiate docs/xxx.md

---
id: version-1.0.0-hello
---

Another content

VS 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 中的 / 作为前文，因此不太可能发生冲突。

¥Since we don't allow / in v1 & v2 for front matter, conflicts are less likely to occur.

因此 v1 用户需要迁移他们的 versioned_sidebars 文件

¥So v1 users need to migrate their versioned_sidebars file

示例 versioned_sidebars/version-1.0.0-sidebars.json：

¥Example 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

¥Populate your versioned_sidebars and versioned_docs

在 v2 中，我们使用快照方法进行文档版本控制。每个版本的文档都不依赖于其他版本。version-1.0.0 中可能有 foo.md，但 version-1.2.0 中不存在。由于 Docusaurus v1 回退功能 (https://v1.docusaurus.io/docs/en/versioning#fallback-functionality)，这在以前的版本中是不可能的。

¥In v2, we use snapshot approach for documentation versioning. Every versioned docs does not depends on other version. It is possible to have foo.md in version-1.0.0 but it doesn't exist in version-1.2.0. This is not possible in previous version due to Docusaurus v1 fallback functionality (https://v1.docusaurus.io/docs/en/versioning#fallback-functionality).

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

¥For example, if your versions.json looks like this in v1

versions.json

["1.1.0", "1.0.0"]

当且仅当文档内容不同时，Docusaurus v1 才会创建版本化文档。如果从 v1.0.0 更改为 v1.1.0 的唯一文档是 hello.md，你的文档结构可能如下所示。

¥Docusaurus v1 creates versioned docs if and only if the doc content is different. Your docs structure might look like this if the only doc changed from v1.0.0 to v1.1.0 is 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 参考）。

¥In v2, you have to populate the missing versioned_docs and versioned_sidebars (with the right front matter and ID reference too).

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 中的样式对象

¥Convert style attributes to style objects in MDX

Docusaurus 2 使用 JSX 来处理文档文件。如果 Docusaurus 1 文档中有任何样式属性，请将它们转换为样式对象，如下所示：

¥Docusaurus 2 uses JSX for doc files. If you have any style attributes in your Docusaurus 1 docs, convert them to style objects, like this:

---
id: demo
title: Demo
---

## Section

hello world

- pre style="background: black">zzz</pre>
+ pre style={{background: 'black'}}>zzz</pre>