버전 지정된 사이트
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_docsid를 확인하세요.
v1에서는 versioned_docs id와 충돌할 수 있는 "version-${version}-${id}" 값을 프런트 매터 id로 사용할 수 있었습니다.
예를 들어 도큐사우루스 1에서는 docs/xxx.md와
---id: version-1.0.0-hello---
Another contentwebsite/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:
{+ "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 파일이 아래와 같은 경우
["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.jsonv2에서는 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: demotitle: Demo---
## Section
hello world
- pre style="background: black">zzz</pre>+ pre style={{background: 'black'}}>zzz</pre>