Antora 플레이북

Antora 플레이북은 기술 작가가 사이트에 포함될 콘텐츠, 적용할 사용자 인터페이스(UI), 그리고 사이트 게시 위치를 쉽게 제어할 수 있게 해주는 도구입니다. 플레이북 파일의 설정은 CLI 옵션 및 환경 변수와 함께 Antora의 작동 방식을 결정합니다.

구체적으로, 플레이북은 Antora에게 다음을 알려줍니다:

또한, 플레이북 파일의 특정 설정은 CLI 옵션이나 환경 변수를 통해 재정의할 수 있어, 운영 팀이 프로덕션과 같은 특정 환경에 맞게 동작을 조정할 수 있습니다.

플레이북은 보통 플레이북 프로젝트에 위치해 있습니다. 플레이북 프로젝트 저장소는 문서 사이트를 생성하는 역할을 담당합니다. 이 저장소는 엄격히 코드로서의 구성(Configuration as Code)을 위한 저장소이며, 콘텐츠는 포함하지 않습니다. 대신, 플레이북 파일과 특정 상황에서는 보조 UI 파일 및 확장 코드가 포함됩니다.

플레이북은 YAML, JSON, TOML로 작성할 수 있습니다. YAML은 자동화 작업을 정의하는 데 흔히 사용되는 설정 언어이며, 이 문서의 대부분의 플레이북 예제는 YAML을 사용합니다. 하지만 이 중 어떤 형식을 사용해도 무방합니다.

형식에 관계없이 플레이북은 일반 사이트 속성, 콘텐츠 및 UI 입력 소스, 게시된 출력 대상 및 제공자를 지정하기 위한 구조화된 키-값 쌍을 포함합니다.

기본적으로 Antora는 플레이북의 상대 경로를 현재 작업 디렉토리에서 해석합니다. 예를 들어, public 경로는 사실상 $PWD/public입니다. 대신 Antora가 플레이북 파일이 있는 디렉토리에서 상대 경로를 해석하도록 하려면 경로 앞에 ./를 붙이세요 (예: ./public).

상대 경로를 ./로 시작하면 플레이북의 이식성이 높아집니다. 이는 파일 시스템의 어느 디렉토리에서 antora 명령을 실행하더라도 동작이 동일하다는 것을 의미합니다.

상대 경로를 ./로 시작하지 않으면 Antora가 해석하는 경로는 현재 작업 디렉토리에 따라 달라집니다. 이식 가능한 동작을 얻으려면 antora 명령을 실행하기 전에 플레이북 파일이 있는 디렉토리로 이동해야 합니다.

현재 작업 디렉토리에 연결하려는 경우에만 맨 앞에 ./가 없는 상대 경로를 사용하세요.