플레이북 설정하기

YAML 형식으로 기본 플레이북 파일을 만들어 봅시다. 다음 섹션의 단계들은 사이트 제목과 URL을 구성하고, Demo Component A와 Demo Component B 저장소에서 소스 파일을 가져오며, 변환된 페이지에 Antora의 참조 UI를 적용하는 플레이북을 설정하는 과정을 안내합니다.

사이트 속성 구성하기

먼저, 사이트의 제목과 URL을 구성해 봅시다.

선호하는 텍스트 편집기나 IDE에서 새 파일을 엽니다. 일반적으로 이 파일의 이름을 antora-playbook.yml로 지정합니다.
첫 줄에 site:를 입력하고 Enter를 눌러 다음 줄로 이동합니다.
site:
site 키는 전역 사이트 속성을 정의하는 키-값 쌍의 맵을 받습니다.
title 키는 site의 하위 항목입니다. title: 를 입력한 다음 사이트의 제목이 될 텍스트를 입력합니다. Enter를 누릅니다.
```
site:
  title: My Demo Site
```
url: 를 입력한 다음 사이트의 기본 URL을 입력합니다.
site: title: My Demo Site url: https://docs.demo.com
url 키에 절대 URL을 할당하면 사이트맵과 같은 부가 기능이 활성화됩니다.
다음 줄에 start_page: 를 입력하고 Antora가 사이트의 홈 페이지로 사용해야 할 페이지의 ID를 입력합니다.
site: title: My Demo Site url: https://docs.demo.com start_page: component-b::index.adoc
위 예시의 start_page 값은 Component B에 속한 index.adoc 파일의 최신 버전에 대한 페이지 ID입니다. Antora가 이 페이지를 사용하려면 Component B에 속한 소스 파일의 위치를 Antora에 알려줘야 합니다.

다음 섹션에서는 콘텐츠 소스 URL, 브랜치, 시작 경로를 정의해 보겠습니다.

사이트의 콘텐츠 소스 구성하기

Antora가 소스 파일을 찾고 가져올 git 저장소, 브랜치, 태그를 알아야 하며, 저장소 루트에 없는 콘텐츠 소스 루트의 위치도 알아야 합니다. 이전 섹션에서 시작한 플레이북 파일에 이러한 키를 정의해 봅시다.

파일의 왼쪽에 맞춰 content:를 입력합니다. Enter를 눌러 다음 줄로 이동합니다.
```
# ...
  start_page: component-b::index.adoc
content:
```
sources 키는 content의 하위 항목입니다. sources:를 입력하고 Enter를 누릅니다.
# ... start_page: component-b::index.adoc content: sources:
sources 키는 최소한 하나의 url 키에 원격 저장소 URL 또는 파일 시스템 경로가 할당되어야 합니다. 다음 단계에서 Demo Component A라는 원격 저장소의 URL을 url에 할당해 보겠습니다.
하이픈(-) 뒤에 공백을 입력합니다. 그런 다음 url: 를 입력하고 콘텐츠 소스 저장소의 URL을 입력합니다.
# ... start_page: component-b::index.adoc content: sources: - url: https://gitlab.com/antora/demo/demo-component-a.git
이제 Antora가 Demo Component A 저장소의 위치를 알 수 있습니다. 하지만 어떤 브랜치와 태그를 가져와야 하는지도 알아야 합니다.

기본 브랜치 필터는 url 키에 branches 또는 tags 키가 설정되지 않았을 때 런타임에 적용됩니다. Demo Component A 저장소에는 브랜치가 하나뿐이고, 그 브랜치의 이름(main)이 기본 필터의 매개변수에 해당하므로 이 url 키에 branches를 명시적으로 설정할 필요가 없습니다.
Demo Component B 저장소의 URL을 추가해 봅시다. 새 줄에 - url: 를 입력하고 저장소의 URL을 입력합니다.
# ... start_page: component-b::index.adoc content: sources: - url: https://gitlab.com/antora/demo/demo-component-a.git - url: https://gitlab.com/antora/demo/demo-component-b.git
Demo Component B 저장소는 버전 관리에 브랜치를 사용합니다. v1.0과 v2.0 브랜치의 콘텐츠 소스 파일이 게시 준비가 되어 있습니다. 그러나 main 브랜치의 파일은 사이트에 게시되어서는 안 되기 때문에 이 url에 기본 브랜치 필터를 사용할 수 없습니다. 대신, Antora에게 Demo Component B 저장소에서 어떤 브랜치를 가져와야 하는지 알려줘야 합니다.

다음 줄에 branches: 와 여는 대괄호([)를 입력합니다. [ 안에 Antora가 가져와야 할 각 브랜치 이름을 입력합니다. 값들을 쉼표로 구분합니다. 브랜치 이름을 나열하는 순서는 중요하지 않습니다. 목록 끝에 닫는 대괄호(])를 입력합니다. Enter를 누릅니다.

# ...
  start_page: component-b::index.adoc
content:
  sources:
  - url: https://gitlab.com/antora/demo/demo-component-a.git
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: [v2.0, v1.0]

url의 u와 branches의 b가 일직선상에 오도록 branches를 충분히 들여쓰세요.

branches 키는 쉘 글로브 패턴도 받아들입니다. 예를 들어, Demo Component B의 url 키에 branches: v*를 정의하여 Antora가 v1.0과 v2.0이라는 이름의 브랜치를 가져오도록 지정할 수 있습니다.

Demo Component B 저장소에 대한 키 구성이 아직 끝나지 않았습니다. 각 브랜치의 콘텐츠 소스 루트가 저장소의 루트에 있지 않고 docs에 있습니다. Antora가 콘텐츠 소스 루트를 찾을 수 있도록 url에 start_path 키를 설정해야 합니다.

start_path: 를 입력하고 저장소 루트에 대한 상대 경로를 입력합니다.

# ...
  start_page: component-b::index.adoc
content:
  sources:
  - url: https://gitlab.com/antora/demo/demo-component-a.git
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: [v2.0, v1.0]
    start_path: docs

경로 앞뒤에 슬래시를 추가하지 마세요.

이제 Antora가 사이트에 적용해야 할 UI를 알려주는 마지막 필수 키 세트를 구성할 준비가 되었습니다.

사이트의 UI 번들 구성하기

Antora는 사이트를 생성하기 위해 UI 번들이 필요합니다. 이전 섹션에서 작업한 플레이북 파일에 필요한 키를 정의하여 Antora에게 참조 UI 번들을 사용하도록 지시해 봅시다.

파일의 왼쪽에 맞춰 ui:를 입력합니다. Enter를 눌러 다음 줄로 이동합니다.
```
# ...
    start_path: docs
ui:
```
bundle 키는 ui의 하위 항목입니다. bundle:을 입력하고 Enter를 누릅니다.
```
# ...
    start_path: docs
ui:
  bundle:
```
url 키는 bundle의 하위 항목입니다. url: 를 입력한 다음 Antora의 참조 UI 번들의 URL을 입력합니다.
# ... start_path: docs ui: bundle: url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
Antora의 참조 UI 아카이브는 시간이 지남에 따라 변경되지만 URL은 변경되지 않으므로 snapshot 키를 활성화해야 합니다.
다음 줄에 snapshot: 를 입력하고 값으로 true를 입력합니다.
# ... start_path: docs ui: bundle: url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable snapshot: true
snapshot이 true로 설정되면 Antora는 플레이북이나 CLI에서 fetch가 활성화될 때마다 UI 번들을 다운로드합니다.

거의 다 완성되었습니다! 지금까지 조립한 전체 플레이북 파일은 다음과 같습니다.

site:
  title: My Demo Site
  url: https://docs.demo.com
  start_page: component-b::index.adoc
content:
  sources:
  - url: https://gitlab.com/antora/demo/demo-component-a.git
  - url: https://gitlab.com/antora/demo/demo-component-b.git
    branches: [v2.0, v1.0]
    start_path: docs
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

이 플레이북은 지정된 저장소 브랜치의 콘텐츠 파일과 지정된 UI 번들의 UI 파일을 사용하여 My Demo Site라는 사이트를 생성합니다.

Antora를 이 플레이북으로 실행하기 전에 해야 할 일은 저장하는 것뿐입니다. 플레이북 파일은 주로 antora-playbook.yml 또는 사용 맥락에 따라 local-antora-playbook.yml과 같은 관련 파일 이름으로 저장됩니다.

플레이북 파일을 저장했다면 이제 Antora를 실행할 준비가 되었습니다.

이 플레이북은 Demo Docs Site 저장소에서도 얻을 수 있습니다.