메인 컨텐츠로 이동
Version: 2.0.0-alpha.75

버전 지정된 사이트

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

note

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

versioned_docs 프런트 매터 이전하기#

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

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

---id: hellotitle: Hello, World !---
Hi, Endilie here :)

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

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

도큐사우루스 2에서 website/versioned_docs/version-1.0.0/hello.md 파일은 아래와 같은 형태입니다(정확하게 원본과 같습니다).

---id: hellotitle: Hello, World !---
Hi, Endilie here :)

내부적으로 스냅샷을 관리해서 버전 내에서 문서를 쉽게 옮기거나 편집할 수 있도록 지원하기 때문에 프런트 매터에서 id를 더 이상 변경할 필요가 없고 그대로 유지할 수 있습니다. 내부적으로는 version-${version}/${id}으로 관리됩니다.

각 versioned_docs 파일에 수정이 필요한 부분은 아래와 같습니다.

---- id: version-1.0.0-hello+ id: hellotitle: 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-hellotitle: 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_sidebarsversioned_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_docsversioned_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: demotitle: Demo---
## Section
hello world
- pre style="background: black">zzz</pre>+ pre style={{background: 'black'}}>zzz</pre>