본문으로 건너뛰기
버전: 2.2.0

버전 지정된 사이트

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

노트

버전 지정된 문서는 일반적으로 마이그레이션 CLI 사용 시 적절하게 이전되어야 합니다.

versioned_docs 프런트 매터 이전하기​

v1과 다르게 버전 지정된 문서의 마크다운 헤더에서 version-${version}-${original_id}을 사용해 실제 ID 필드 값으로 변환할 필요가 없습니다. 이해를 돕기 위해 아래 시나리오를 참고하세요.

예를 들어 여러분은 docs/hello.md 문서를 가지고 있습니다.

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

Hi, Endilie here :)

도큐사우루스 v1에서는 새로운 1.0.0 버전을 생성하면 아래와 같이 website/versioned_docs/version-1.0.0/hello.md 파일이 만들어집니다.

---
id: version-1.0.0-hello
title: Hello, World !
original_id: hello
---

Hi, Endilie here :)

도큐사우루스 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 이전하기​

  • version-${version}-${original_id} (v1) 대신 version-${version}/${id} (v2)에서 versioned_docs ID를 확인하세요.

v1에서는 versioned_docs ID와 충돌할 수 있는 "version-${version}-${id}" 값을 프런트 매터 ID로 사용할 수 있었습니다.

예를 들어 도큐사우루스 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에서 우리는 문서 버전 관리를 위해 스냅샷 방식을 사용합니다. 모든 버전의 문서는 다른 버전 문서와 엮여 있지 않습니다. 때문에 foo.md 문서가 version-1.0.0에는 있지만 version-1.2.0에는 없을 수도 있습니다. 도큐사우루스 v1에서는 폴백 기능(https://v1.docusaurus.io/docs/en/versioning#fallback-functionality) 때문에 이런 일은 생길 수가 없었습니다.

예를 들어 v1에 versions.json 파일이 아래와 같은 경우

versions.json
["1.1.0", "1.0.0"]

도큐사우루스 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 스타일 오브젝트로 바꾸기​

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

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

## Section

hello world

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