메인 컨텐츠로 이동
Version: 2.0.0-beta.0

버전 관리

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

caution

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

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

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

디렉터리 구조#

website├── sidebars.json        # master(next) 버전을 위한 sidebar를 설정하는 파일입니다.├── docs                 # master(next) 버전을 위한 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

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

경로버전URL
versioned_docs/version-1.0.0/hello.md1.0.0/docs/1.0.0/hello
versioned_docs/version-1.1.0/hello.md1.1.0 (최신)/docs/hello
docs/hello.mdnext/docs/next/hello

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

  1. 먼저 docs 디렉터리에 있는 콘텐츠가 버전을 부여받을 준비가 되어 있는지 확인합니다. 버전은 언제나 마스터를 기반으로 동작해야 합니다.
  2. 새로운 버전 번호를 부여합니다.
npm run docusaurus docs:version 1.1.0

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

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

문서#

새 문서 만들기#

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

마스터 문서

# 새로운 파일docs/new.md
# 연결된 사이드바 파일도 편집합니다.sidebar.js

이전 문서

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

문서 링크#

  • .md 확장자를 포함해야 합니다.
  • 파일은 정확히 대응하는 버전으로 링크되어야 합니다.
  • 상대 경로로 설정할 수도 있습니다.
The [@hello](hello.md#paginate) document is great!
See the [Tutorial](../getting-started/tutorial.md) for more info.

버전 관리#

versioned_docs/의 각 디렉터리는 문서 버전을 나타냅니다.

기존 버전 업데이트하기#

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

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

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

기존 버전 삭제하기#

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

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

예:

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

권장하는 방안#

"current" 버전이 어떻게 동작하는지 알아야 합니다.#

"current" 버전은 ./docs 디렉터리의 버전명입니다.

버전을 관리하는 방법은 다양하지만 두 가지 공통적인 패턴을 가지고 있습니다.

  • v1 버전을 출시하고 곧바로 v2 버전 작업을 진행합니다(문서도 마찬가지입니다).
  • v1 버전을 출시하고 v2 버전을 시작하기 전에 일정 기간 유지 관리되는 기간이 있습니다.

도큐사우루스는 기본적으로 첫 번째 패턴에 적절합니다.

두 번째 패턴을 적용해야 한다면: 여러분이 v1 버전을 출시하고 v2 버전은 언제 출시될지 아직 계획이 없다면 2개 디렉터리(./docs + ./versioned_docs/version-1.0.0)에서 문서를 관리하는 대신 다음과 같은 설정을 검토해볼 수 있습니다.

{  "lastVersion": "current",  "versions": {    "current": {      "label": "1.0.0",      "path": "1.0.0"    }  }}

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

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

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

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

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

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

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

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

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

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

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

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

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

![img alt](./myImage.png)
[download this file](./file.pdf)

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

![img alt](/myImage.png)
[download this file](/file.pdf)