分版站点

先阅读 https://docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning 来了解从 v1 迁移可能带来的问题。

备注

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

Migrate your versioned_docs front matter

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. 为了更好地解释请看下方的场景。

For example, if you have a docs/hello.md.

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

Hi, Endilie here :)

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

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

既然我们正在使用快照版本应允许用户简便地在版本内移动 (和编辑) 文档。 The id front matter is no longer altered and will remain the same. Internally, it is set as version-${version}/${id}.

基础地，这是每个版本的 docs 文件中的必要更改：

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

Migrate your versioned_sidebars

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

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.

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

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

所以 v1 版本需要迁移他们的 versioned_sidebars 文件

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"
    ]
  }
}

Populate your versioned_sidebars and versioned_docs

在 v2 版本中，我们使用快照方法进行文档版本管理。 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. 由于Docusaurus v1 的回退功能，这在前一版本中是不可行的 (https://v1.docusaurus.io/docs/en/versioning#fallback-function).

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

versions.json

["1.1.0", "1.0.0"]

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

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

Convert style attributes to style objects in 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>