버전: Canary 🚧

버전 관리

docs 디렉토리에서 마지막으로 작성한 콘텐츠를 기준으로 새로운 문서를 만들기 위해 versioning CLI를 사용할 수 있습니다. docs 디렉토리 내 문서가 바뀌더라도 지정된 문서 세트는 그대로 유지되고 접근할 수 있습니다.

warning

여러분의 문서에서 버전 관리를 시작하기 전에 충분한 검토가 필요합니다. 기여자들이 문서 내용을 개선하는 데 어려움이 생길 수도 있습니다.

일반적으로 버전 관리가 필요하지는 않습니다. 버전 관리 기능을 활성화하면 빌드 시간이 길어지고 코드의 복잡도도 늘어납니다. 버전 관리는 방문자가 많고 버전간 문서 내용이 빠르게 변경되는 경우에 적합합니다. 여러분이 관리하는 문서가 거의 변경이 없다면 버전 관리 기능을 사용할 필요는 없습니다.

버전 관리 기능이 어떻게 동작하고 여러분에게 필요한지 확인하려면 아래 내용을 계속 읽어주세요.

개요

일반적으로 버전이 지정된 문서 사이트는 아래와 같은 형태입니다.

website
├── sidebars.json        # 현재 버전 문서의 사이드바
├── docs                 # 현재 버전 문서의 문서 디렉터리
│   ├── foo
│   │   └── bar.md       # https://mysite.com/docs/next/foo/bar
│   └── hello.md         # https://mysite.com/docs/next/hello
├── versions.json        # 사용할 수 있는 버전 정보가 명시된 파일
├── versioned_docs
│   ├── version-1.1.0
│   │   ├── foo
│   │   │   └── bar.md   # https://mysite.com/docs/foo/bar
│   │   └── hello.md
│   └── version-1.0.0
│       ├── foo
│       │   └── bar.md   # https://mysite.com/docs/1.0.0/foo/bar
│       └── hello.md
├── versioned_sidebars
│   ├── version-1.1.0-sidebars.json
│   └── version-1.0.0-sidebars.json
├── docusaurus.config.js
└── package.json

versions.json 파일은 최신 버전에서 가장 오래된 버전까지 정렬된 버전 이름 목록입니다.

아래 표에서는 버전과 생성된 URL이 어떤 파일과 연결되는지 설명합니다.

경로	버전	URL
`versioned_docs/version-1.0.0/hello.md`	1.0.0	/docs/1.0.0/hello
`versioned_docs/version-1.1.0/hello.md`	1.1.0 (최신)	/docs/hello
`docs/hello.md`	current	/docs/next/hello

팁

docs 디렉터리에 속한 파일은 current 문서 버전에 해당합니다.

기본적으로 current 문서 버전은 Next 라벨로 지정되고 /docs/next/* 디렉터리에 위치하게 되지만 여러분의 프로젝트 릴리스 정책에 따라 설정할 수 있습니다.

용어

여기에서 사용하는 용어에 유의하세요.

현재 버전(Current version): ./docs 폴더에 있는 버전입니다.
최신 버전(Latest version / last version): 문서 메뉴바 아이템에서 기본적으로 제공되는 버전입니다. 일반적인 경로는 /docs입니다.

현재 버전은 파일 시스템 위치로 정의되고 최신 버전은 탐색 동작으로 정의됩니다. 같은 버전이 될 수도 있고 그렇지 않을 수도 있습니다! (위에 표에서 보여주는 것처럼 기본 구성은 다른 것으로 취급합니다. 현재 버전은 /docs/next에 최신 버전은 /docs에 있습니다).

따라해보기

새로운 버전으로 태그 추가하기

먼저 current 문서 버전(./docs 디렉터리)이 최종 상태인지 확인합니다.
새로운 버전 번호를 부여합니다.

npm
Yarn
pnpm

npm run docusaurus docs:version 1.1.0

yarn docusaurus docs:version 1.1.0

pnpm run docusaurus docs:version 1.1.0

새로운 버전으로 태그를 추가할 때 문서에서 아래와 같이 버전을 처리합니다.

docs/ 디렉터리에 있는 콘텐츠 전체를 versioned_docs/version-[versionName]/ 디렉터리를 만들고 그 안에 복사합니다.
현재 사이드바 설정을 기반(기존 설정이 있는 경우)으로 새로운 버전의 사이드바를 만들면 versioned_sidebars/version-[versionName]-sidebars.json 형식으로 파일이 생성됩니다.
새로운 버전 번호를 versions.json 파일에 추가합니다.

새 문서 만들기

새로운 파일을 해당하는 버전 디렉터리에 가져다 놓습니다.
버전 번호에 따라 연결된 사이드바 설정 파일에 새로운 파일에 대한 참조를 추가합니다.

Current version structure
Older version structure

# 새로운 파일
docs/new.md

# 연결된 사이드바 파일도 편집합니다.
sidebars.js

# 새로운 파일
versioned_docs/version-1.0.0/new.md

# 연결된 사이드바 파일도 편집합니다.
versioned_sidebars/version-1.0.0-sidebars.json

기존 버전 업데이트하기

versioned_docs/의 각 디렉터리는 배포 시 특정 경로로 연결되기 때문에 여러 문서 버전을 한 번에 업데이트할 수 있습니다.

파일을 수정합니다.
변경사항을 커밋하고 푸시합니다.
해당 버전으로 게시됩니다.

예: versioned_docs/version-2.6/ 디렉터리 안의 파일을 수정하면 2.6 버전에 해당하는 문서만 영향을 받습니다.

기존 버전 삭제하기

특정 버전을 삭제할 수도 있습니다.

versions.json 파일에서 해당 버전을 삭제합니다.

예:

[
  "2.0.0",
  "1.9.0",
- "1.8.0"
]

해당 버전의 문서 디렉터리를 삭제합니다. 예: versioned_docs/version-1.8.0.
해당 버전의 사이드바 파일을 삭제합니다. 예: versioned_sidebars/version-1.8.0-sidebars.json.

버전 관리 동작 구성

"current" 버전은 ./docs 디렉터리의 버전명입니다. 버전을 관리하는 방법은 다양하지만 두 가지 공통적인 패턴을 가지고 있습니다.

v1 버전을 출시하고 곧바로 v2 버전 작업을 진행합니다(문서도 마찬가지입니다). 이 경우에는 현재 버전은 ./docs 소스 폴더에 있는 v2이며 example.com/docs/next 형식으로 접근할 수 있습니다. 최신 버전은 ./versioned_docs/version-1 소스 폴더에 있는 v1이며 example.com/docs 형식으로 대부분의 사용자가 접근하게 됩니다.
v1 버전을 출시하고 v2 버전을 시작하기 전에 일정 기간 유지 관리되는 기간이 있습니다. 이 경우 v2 문서가 아직 존재하지 않기 때문에 현재 버전과 최신 버전 모두 v1 문서를 가리킵니다.

도큐사우루스는 기본적으로 첫 번째 패턴에 적절합니다. 현재 버전에 "next"라는 라벨을 지정하고 게시되지 않도록 선택할 수도 있습니다.

두 번째 패턴을 적용해야 한다면: 여러분이 v1 버전을 출시하고 v2 버전은 언제 출시될지 아직 계획이 없다면 v1 버전을 관리하고 2개 디렉터리(./docs + ./versioned_docs/version-1.0.0)에서 문서를 관리하는 대신 경로와 라벨을 지정해 현재버전이 최신 버전인 것"처럼" 하는 것을 고려해볼 수 있습니다.

docusaurus.config.js
export default {
  presets: [
    '@docusaurus/preset-classic',
    docs: {
      lastVersion: 'current',
      versions: {
        current: {
          label: '1.0.0',
          path: '1.0.0',
        },
      },
    },
  ],
};

./docs 디렉터리 안에 있는 문서는 /docs/next 대신 /docs/1.0.0에서 서비스됩니다. 그리고 1.0.0은 메뉴바 드롭다운 목록에서 기본 버전 링크로 연결됩니다. 여러분은 ./docs 디렉터리 하나만 관리하면 됩니다.

사용자 지정 버전 관리 동작을 위해 아래와 같은 플러그인 옵션을 제공합니다.

disableVersioning: 버전이 있는 경우 버전 관리 기능을 명시적으로 비활성화할지를 설정합니다. 이렇게 하면 사이트에 현재 버전만 포함됩니다.
includeCurrentVersion: 여러분의 문서에 현재 버전(./docs 폴더)을 포함합니다.
- 팁: 현재 버전이 작업 상태이며 게시할 준비가 되지 않았다면 옵션을 꺼주세요.
lastVersion: "최신 버전"(/docs 경로)이 가리키는 버전을 설정합니다.
- Tip: lastVersion: 'current' 설정은 현재 버전이 지속적으로 패치되고 릴리스되는 주요 버전을 참조하는 경우 의미가 있습니다. 최신 버전의 실제 라우트되는 base 경로와 라벨을 설정할 수 있습니다.
onlyIncludeVersions: 배포할 versions.json 버전의 하위 집합을 정의합니다.
- 팁: 시작과 빌드 시간을 개선하기 위해 개발 시에서는 2 또는 3개 버전으로 제한하고 미리 보기를 배포합니다.
versions: 버전 메타데이터 목록입니다. 각 버전에 대해 다음 항목을 사용자 지정할 수 있습니다.
- label: 버전 드롭다운 목록이나 배너에 표시될 라벨입니다.
- path: 버전의 라우트 base 경로입니다. 기본적으로 최신 버전은 / 최신 버전은 /next입니다.
- banner: 'none', 'unreleased', 'unmaintained' 중 하나를 설정합니다. 모든 문서 페이지 상단에 표시되는 내용을 지정합니다. 최신 버전보다 높은 버전은 "unreleased" 최신 버전보다 낮은 버전은 "unmaintained"가 됩니다.
- badge: 해당 버전 문서 상단에 버전 이름과 같이 배지를 표시합니다.
- className: 사용자 지정 className을 해당 버전 문서 페이지의 <html> 요소에 추가합니다.

좀 더 자세한 내용은 docs 플러그인 설정 문서를 참고하세요.

버전에 따른 경로를 신경쓰지 않고 빠르게 탐색을 설정할 수 있게 여러가지 메뉴바 아이템을 제공합니다.

doc: 문서에 대한 링크
docSidebar: 사이드바 첫 번째 아이템에 대한 링크
docsVersion: 현재 보고 있는 버전의 기본 문서에 대한 링크
docsVersionDropdown: 사용할 수 있는 모든 버전이 포함된 드롭다운

이런 링크는 모두 다음 순서로 연결할 적절한 버전을 찾습니다.

활성화 버전(Active version): 사용자가 문서 플러그인에서 제공하는 페이지에 있는 경우 현재 탐색하고 있는 버전입니다. 문서 페이지에 있는 것이 아니라면 다시 적절한 버전을 찾습니다.
기본 버전(Preferred version): 사용자가 최근에 본 버전입니다. 탐색 이력이 없다면 다시 적절한 버전을 찾습니다.
최신 버전(Latest version): lastVersion 옵션으로 설정된 기본 버전입니다.

권장하는 방안

필요한 경우에만 문서 버전을 추가하세요

예를 들어 여러분의 npm 패키지 foo에 대한 문서를 작성하고 현재 버전은 1.0.0이라고 생각해보죠. 소소한 버그 수정이 반영된 패치버전이 배포했습니다. 이제 1.0.1 버전이 됐습니다.

그럼 문서 버전도 1.0.1로 변경해야 할까요? 그렇지 않습니다. 1.0.1과 1.0.0 문서는 유의적 버전(semver)을 기준으로 새로운 기능이 없으므로 다르지 않아야 합니다. 새로운 버전으로 구분하게 되면 불필요하게 중복된 파일만 생겨나게 됩니다.

버전 개수는 적게 유지하세요

경험상 버전 개수는 10개 이하로 유지하는 것이 좋습니다. 오래된 버전의 문서는 아마도 대부분 아무도 읽지 않을 가능성이 높습니다. 예를 들어 제스트(Jest)는 현재 버전이 27.4이며 최근 몇 개의 문서 버전만 유지하고 있습니다. 가장 낮은 버전은 25.X입니다. 작게 유지하세요 😊

오래된 버전 보관하기

잼스택 제공자(예를 들어 Netlify)에 사이트를 배포하는 경우 제공자는 각 제품 빌드를 변경할 수 없는 URL 아래에 스냅샷으로 저장합니다. 이런 변경할 수 없는 URL에 대한 외부 링크로 다시 작성될 일이 없는 보관할 버전을 포함할 수 있습니다. Jest 웹사이트와 도큐사우루스 웹사이트는 이런 패턴을 사용해 활성화된 버전의 숫자를 낮게 유지하니다.

문서 내에서 절대 경로 가져오기를 사용하세요

문서 내에서 가져오기 시 상대 경로를 지정하지 마세요. 버전을 추가할 때 해당 경로가 더 이상 동작하지 않을 수 있어(중첩 수준이 다르거나 그 외 여러 이유로) 도큐사우루스에서 제공하는 @site 별칭을 사용해 website 디렉터리를 가리키도록 설정할 수 있습니다. 예:

- import Foo from '../src/components/Foo';
+ import Foo from '@site/src/components/Foo';

파일 경로로 문서 링크

.md 확장자를 가진 상대 파일 경로로 다른 문서를 참조하면 도큐사우루스가 빌드하는 동안 실제 URL 경로로 다시 작성할 수 있습니다. 파일은 정확히 대응하는 버전으로 링크되어야 합니다.

The [@hello](hello.mdx#paginate) document is great!

See the [Tutorial](../getting-started/tutorial.mdx) for more info.

공용 애셋을 전역으로 사용할지 버전별로 구분할지 결정하세요

이미지나 파일 같은 애셋을 버전별로 구분할지 아니면 버전끼리 공유하도록 할지 결정해야 합니다.

버전별로 애셋을 구분한다면 문서 버전에 따라 파일을 넣고 상대 경로를 사용합니다.

![img alt](./myImage.png)

[download this file](./file.pdf)

애셋을 전역으로 사용한다면 /static 디렉터리에 넣고 절대 경로를 사용합니다.

![img alt](/myImage.png)

[download this file](/file.pdf)

버전 관리

개요​

용어​

따라해보기​

새로운 버전으로 태그 추가하기​

새 문서 만들기​

기존 버전 업데이트하기​

기존 버전 삭제하기​

버전 관리 동작 구성​

메뉴바 아이템​

권장하는 방안​

필요한 경우에만 문서 버전을 추가하세요​

버전 개수는 적게 유지하세요​

문서 내에서 절대 경로 가져오기를 사용하세요​

파일 경로로 문서 링크​

공용 애셋을 전역으로 사용할지 버전별로 구분할지 결정하세요​

개요

용어