버전 지정된 사이트

v1에서 사용한 접근방식의 문제점을 https://docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning 글에서 먼저 확인해주세요.

노트

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}.

각 versioned_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. 도큐사우루스 v1에서는 폴백 기능(https://v1.docusaurus.io/docs/en/versioning#fallback-functionality) 때문에 이런 일은 생길 수가 없었습니다.

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

도큐사우루스 2에서는 문서 파일에서 JSX를 사용합니다. 도큐사우루스 1 문서에 스타일 속성을 설정했다면 아래와 같이 스타일 오브젝트로 바꾸어줘야 합니다.

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

## Section

hello world

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