Antora가 귀하와 팀에 도움이 될 수 있는 방법

CMS 거인과 씨름하는 대신 변경사항이 발생할 때마다 안전하고 빠른 정적 사이트의 조립을 자동화하세요.

어떤 변경에도 몇 초 만에 사이트를 자동으로 재구축하고 배포할 수 있습니다. 배포된 CMS 애플리케이션의 보안 취약점 패치에 대해 걱정할 필요가 없습니다. 왜냐하면 그런 것이 없기 때문입니다. 모든 페이지는 JAMstack(JavaScript, API, Markup) 스타일로 만들어지고 정적입니다. 사이트를 다른 도메인으로 마이그레이션해야 합니까? 사이트를 재구축하고 새 호스트에서 다시 시작하면 됩니다. Antora는 가장 순수한 의미에서 정적인 사이트를 생성합니다. 이 사이트는 어떤 웹 서버에서든, 어떤 도메인이나 서브도메인에서든, 하위 폴더 내에서도, 심지어 로컬 파일 시스템에서도 실행될 수 있습니다.

다른 웹 속성과 원활하게 어울리도록 사이트를 조정하세요.

어떤 사이트도 섬이 아닙니다. 사이트는 일관된 브랜드와 사용자 경험을 유지하기 위해 다른 사이트들과 잘 어울려야 합니다. Antora로 생성된 정적 사이트는 이 역할에 잘 어울립니다. 페이지 템플릿과 자동화 프로세스의 도움을 받아 문서 페이지를 기존 사이트에 혼합할 수 있어, 모든 것이 단일한 통일된 사이트의 일부라는 인상을 줄 수 있습니다.

git 기반 CI 워크플로우를 사용하여 문서 변경, 기여 및 이니셔티브를 관리하세요.

개발이 이루어지는 곳으로 가세요. GitHub, GitLab, Bitbucket 또는 다른 코드 호스팅 서비스에서 *Docs as Code*를 개발할 수 있습니다. git 기반 CI 워크플로우는 무료로 협업 및 리뷰 도구를 제공할 뿐만 아니라 팀 간 협업을 장려합니다. 결과적으로 문서는 소프트웨어 개발 프로세스의 일부가 됩니다. 그리고 이는 더 많은 사람들이 문서 개선 노력을 지원할 준비가 되어 있다는 것을 의미합니다.

기존 개발 인프라를 활용하여 팀과 권한을 관리하세요.

아마도 귀하의 소프트웨어 제품에는 이미 잘 정의된 팀, 권한 구조 및 기여자 커뮤니티가 있을 것입니다. 동일한 조직을 사용하거나 이를 기반으로 문서 팀을 관리할 수 있습니다. 이러한 플랫폼은 활동을 모니터링하거나 특정 작업을 수행할 수 있는 권한을 부여하는 등 문서의 관리 및 운영 인터페이스 역할을 할 수 있습니다.

만들고 싶은 것을 설명하면 Antora가 나머지를 처리합니다.

Antora는 콘텐츠 작성자를 위해 먼저 만들어졌습니다. 콘텐츠 작성자는 소프트웨어 재구성에 신경 쓰지 않고 글을 쓰고 싶어 합니다. 여기서 Antora의 플레이북이 등장합니다. 플레이북은 생성하고자 하는 사이트를 간결하게 설명하는 방법입니다. 이 설명은 a) 콘텐츠를 어디서 가져올지, b) 페이지에 어떤 UI를 적용할지, c) 어디에 게시할지로 요약됩니다. 이것이 Antora가 작업을 수행하는 데 필요한 전부입니다. 추가적인 사용자 정의를 원할 때만 더 깊이 들어갈 필요가 있습니다.

오프라인 우선.

Antora를 사용하여 생성된 사이트는 완전히 오프라인으로 볼 수 있습니다. 사이트의 모든 참조는 자체 포함(즉, 상대적)되어 있어 웹 서버를 실행할 필요가 없습니다. 생성된 HTML 파일 중 하나를 브라우저에서 열기만 하면 UI에서 모든 페이지로 이동할 수 있습니다. 리디렉션도 기본적으로 오프라인에서 작동합니다. 웹 서버가 사용 가능한 경우, 추가 구성을 전달하여 Antora가 그 기능을 활용하도록 지시할 수 있습니다.

저장소 경계와 브랜치를 넘나드는 문서를 단일 빌드로 집계하세요.

대부분의 사이트 생성기는 단일 저장소의 단일 브랜치로 제한됩니다. 반면에 Antora는 git을 이해합니다. 내장된 git 클라이언트를 사용하여 사이트에 필요한 모든 콘텐츠를 수집합니다. 그런 다음 파일을 컴포넌트의 버전별로 정리합니다. 이를 통해 조직에 가장 적합한 방식으로 문서를 저장할 수 있으며, 코드와 함께 콘텐츠를 보관하거나 별도의 저장소를 사용할 수 있습니다. Antora는 이러한 모든 분산된 프로젝트와 저장소를 모아 통합된 사이트를 만들 수 있습니다.

콘텐츠를 선별하여 사이트를 수작업으로 만드세요.

항상 모든 것을 사이트에 포함시키고 싶지는 않을 것입니다. 때로는 제품이나 버전의 축소된 선택을 포함하는 "마이크로사이트"를 구축하고 싶을 수 있습니다. 또는 현재 작업 중인 제품의 문서만 미리 보고 싶을 수도 있습니다. 플레이북을 사용하면 동일한 콘텐츠 소스에서 어떤 소스를 사용할지 조정하여 여러 가지 사이트 변형을 생성할 수 있습니다.

하나의 사이트의 일부로 제품의 각 버전을 구축하세요.

소프트웨어는 버전이 있으므로 그에 대한 문서도 버전이 있어야 합니다. 그렇지 않으면 사용자들은 어떤 버전의 소프트웨어에 대한 문서를 읽고 있는지 모르게 되어버리고, 혼란이 생깁니다. 소프트웨어와 마찬가지로 브랜치와 태그를 사용하여 문서의 버전을 관리할 수 있습니다. 이 콘텐츠는 소프트웨어 자체와 함께 저장될 수도 있습니다. Antora는 이 모든 콘텐츠를 기꺼이 수집하고 구성하여 사용자가 단일 사이트에서 각 버전의 문서에 접근할 수 있도록 합니다.

다른 제품 버전을 탐색하거나 버전 간 페이지를 탐색하세요.

여러 버전의 문서가 있으면 사용자가 그들을 탐색할 방법이 필요합니다. Antora는 독자에게 메뉴로 제공되는 문서 컴포넌트와 버전의 카탈로그를 제공합니다. 독자는 메뉴를 스캔하고 필요한 버전의 문서로 바로 이동할 수 있습니다. 또한 각 페이지는 버전 시퀀스의 일부로 자체 식별할 수 있어, 사용자가 페이지의 이전 또는 최신 버전의 콘텐츠를 빠르게 방문할 수 있습니다.

기술 문서를 위해 특별히 설계된 직관적인 구문을 사용하여 문서를 작성하세요. 가볍지만 포괄적입니다.

문서를 작성할 때 마크업 구문이 방해가 되는 것은 원하지 않습니다. 최고의 콘텐츠를 만들려면 쓰고 있는 내용을 볼 수 있어야 하지만, 여전히 다른 콘텐츠 유형을 적절하게 표현할 수 있어야 합니다. 이것이 바로 AsciiDoc이 제공하는 것입니다. 줄 중심의 왼쪽 정렬 구문은 쉽게 탐색할 수 있으며 의미 구조를 구축하기 위해 충분한 메타데이터를 적용할 여지를 남깁니다. AsciiDoc은 문서 작성자의 가장 좋은 친구입니다.

재사용 가능한 속성, 포함, 구문 확장을 사용하여 콘텐츠를 DRY하게 유지하세요.

이전에 입력한 것을 다시 입력할 때마다 효율성을 잃고 내용이 분기될 위험을 초래합니다. AsciiDoc은 반복을 피할 수 있는 여러 도구를 제공합니다. 속성을 사용하여 URL, 제품 이름 또는 정의를 여러 번 입력하지 않아도 됩니다. 포함을 사용하여 전체 단락, 섹션 및 기타 재사용 가능한 콘텐츠를 공통 파일로 추출할 수 있습니다. 그리고 구문 확장을 도입하여 이슈 트래커에 대한 참조나 방정식 및 차트와 같은 새로운 유형의 콘텐츠와 같이 자주 반복되는 패턴을 간략화할 수 있습니다.

페이지는 단순히 모든 텍스트 편집기에서 편집할 수 있는 AsciiDoc 문서입니다.

문서에 페이지를 만드는 것은 AsciiDoc 문서를 만드는 것만큼 간단합니다. 문서는 텍스트 편집기에서 열어 미리 볼 수 있거나 사이트 컨텍스트에서 볼 수 있습니다. Antora는 페이지에 암시적 ID를 할당하여 다른 페이지에서 참조할 수 있게 하며, 다른 페이지의 암시적 ID를 사용하여 해당 페이지를 참조할 수 있습니다. 섹션 제목, 주의사항 블록, 강조된 소스 목록과 같은 기능은 적절하게 스타일이 지정됩니다.

간결하고 쉽게 구성할 수 있는 소스 간 xref 시스템을 사용하여 페이지와 다른 리소스 간의 참조를 만드세요.

생성된 파일 이름이나 URL에 의존하는 대신, 대상의 소스 시스템 위치를 사용하여 페이지와 다른 리소스 간의 참조를 만듭니다. 이렇게 하면 참조에 대한 추론이 쉬워집니다. 소스 파일의 위치만 생각하면 되고 처리 방식은 고려할 필요가 없기 때문입니다. 즉, 소스 경로 안에서 작업하게 됩니다. 그리고 현재 소스 파일의 컨텍스트의 이점을 얻어, 현재 컨텍스트와 다른 대상의 특성만 지정하면 됩니다.

소스 간 참조는 사이트를 파일 시스템 및 게시 환경에서 분리하는 데 필요한 정보를 제공합니다.

리소스 ID를 사용하여 참조를 표현함으로써 Antora는 파일 시스템이나 게시 환경과 연결되지 않은 게시된 출력의 리소스에 대한 링크를 지능적으로 생성할 수 있습니다. 이는 생성된 사이트를 오프라인을 포함한 어디에서나 볼 수 있다는 것을 의미합니다.

AsciiDoc 목록을 사용하여 문서 내비게이션을 설명하세요.

Antora를 사용하는 작성자는 내비게이션을 정의할 때 편안함을 느낄 수 있습니다. 왜일까요? 왜냐하면 페이지와 마찬가지로 내비게이션도 그저 또 다른 AsciiDoc 문서이기 때문입니다. 하지만 자유 형식의 콘텐츠 대신, 내비게이션 파일은 내비게이션 메뉴 사이드바에서 볼 수 있는 내비게이션 트리로 변환되는 목록 계층을 포함합니다. 다른 내비게이션 트리를 추가하려면 단순히 추가 목록을 추가하면 됩니다.

주요 콘텐츠에서 사용되는 것과 동일한 xref 시스템을 사용하여 내비게이션 링크를 만드세요.

그렇다면 내비게이션에서 페이지로의 링크는 어떻게 만들까요? 물론 xref를 사용합니다. 내비게이션 파일은 단순히 콘텐츠이기 때문에, 페이지 간 링크를 만드는 데 사용되는 것과 동일한 xref 시스템을 사용할 수 있습니다. 내비게이션 파일을 게시되지 않는 페이지로 생각하세요. 그리고 파일이 콘텐츠와 함께 저장되므로 xref는 컨텍스트에 따라 달라질 수 있습니다. 즉, 현재 컨텍스트와 다른 대상의 특성만 지정하면 됩니다.

사이트의 사용자 인터페이스와 테마는 콘텐츠와 별도로 유지됩니다.

Antora의 주요 테마 중 하나는 콘텐츠와 표현의 분리입니다. 이는 UI에서 두드러지게 나타납니다. Antora는 별도의 프로젝트로 저장되고 관리되는 사이트 UI와 상호작용합니다. UI가 제공한 Handlebars 템플릿에 UI 모델을 전달합니다. 그런 다음 템플릿은 모델에서 표시할 내용을 결정하여 UI에 페이지 레이아웃을 완전히 제어할 수 있게 합니다. 템플릿은 또한 포함할 CSS와 JavaScript를 결정합니다.

콘텐츠와 독립적으로 UI를 반복합니다.

UI와 콘텐츠가 별도로 유지되므로 다른 릴리스 주기를 따를 수 있습니다. 그리고 서로 방해하지 않습니다. UI에서 수행된 작업은 콘텐츠에서 수행된 작업을 방해하지 않습니다. Antora가 실행되면 최신 콘텐츠와 최신 UI를 융합합니다. 이는 한 UI와 테마를 다른 것으로 쉽게 교체할 수 있음을 의미하며, 이는 재설계, A/B 테스팅 또는 캠페인에 유용할 수 있습니다. 귀하의 요구에 맞게 UI와 테마를 최대한 자유롭게 조정할 수 있습니다.

대상 문서에 정보를 저장하여 투명한 방식으로 이전 페이지의 URL을 유지하세요.

변화는 항상 일어납니다. 중요한 것은 그것을 대처할 준비가 되어 있는지입니다. 문서 사이트에서 가장 자주 변경되는 것 중 하나는 페이지의 URL입니다. 페이지 이름이 바뀌거나 재구성될 때 변경됩니다. Antora는 페이지 별칭을 선언하여 이전 페이지의 URL을 유지하는 방법을 제공합니다. Antora의 다른 기능과 마찬가지로 이 정보는 콘텐츠와 함께 저장되며, 이 경우 대상 AsciiDoc 문서의 헤더에 저장됩니다.

리디렉션은 별칭을 사용하여 설명되며, 이는 단순히 인바운드 xref입니다. URL과 연결되지 않습니다.

예상할 수 있듯이, 페이지 별칭은 소스 참조이며, 이를 통해 Antora가 올바른 URL에서 리디렉션을 생성하도록 할 수 있습니다. 모든 호스팅 환경이 동일하지 않으므로 리디렉션을 수행하는 기능도 다릅니다. Antora는 호스팅 환경이 제공하는 리디렉션 기능에 대한 적절한 구성을 생성하며, 다른 메커니즘이 지원되지 않는 경우 오래된 정적 바운스 페이지로 대체합니다.

로컬이든 원격이든 어디에나 게시하세요.

사이트는 게시되기 위해 만들어집니다. Antora가 이를 도와줍니다. 목적지가 로컬이든 원격이든 Antora는 내장 또는 사용자 정의 제공자를 사용하여 그곳으로 콘텐츠를 스트리밍합니다. 그럼에도 불구하고 사이트가 어디에 게시되든 호스트 환경과 연결되지 않습니다. Antora는 원하는 만큼의 출력 스트림을 지원하며, 이는 로컬 디렉토리, 로컬 아카이브, 원격 SSH 서버의 디렉토리, S3와 같은 웹 서비스 엔드포인트 또는 목적지의 조합일 수 있습니다. Antora가 게시를 위해 파일을 필요한 곳으로 보내는 것을 확신할 수 있습니다. 모두 단일 빌드에서 이루어집니다.

파이프라인에 별도의 단계, 도구 또는 스크립트가 필요 없습니다.

Antora의 파일 게시자는 파이프라인에서 한 단계를 절약해줍니다. 대부분의 사이트 생성기는 출력을 로컬 디렉토리에 쓰며, 이를 다시 게시해야 합니다. Antora는 출력을 지정한 목적지로 직접 보냅니다. 그리고 사이트의 참조가 게시 환경과 연결되어 있지 않기 때문에 로컬 디렉토리에 게시하여 오프라인으로도 사이트를 미리 볼 수 있습니다.

기본값으로 시작하세요.

Antora는 즉시 사용 가능한 의견이 있는 사이트 생성기와 UI를 제공하여 빠르게 시작할 수 있습니다. antora CLI 명령을 사용하여 사이트 생성기와 인터페이스할 수 있으며, 이는 직접 설치하거나 Docker 컨테이너를 사용하여 호출할 수 있습니다. 플레이북을 명령에 지정하기만 하면 Antora가 다중 컴포넌트, 다중 버전 문서 사이트를 생성합니다. Antora와 함께 사용할 문서를 설정하거나 마이그레이션할 기회를 가진 후에는 기본값에서 벗어나 고급 요구 사항에 맞게 Antora를 조정하기 시작할 수 있습니다.

Antora를 귀하에게 맞게 조정하세요.

Antora는 개방형 아키텍처를 특징으로 합니다. 이것이 무엇을 의미할까요? Antora에 새로운 기능을 추가할 수 있다는 의미입니다. 아마도 Antora의 카탈로그에 추가 콘텐츠를 통합해야 할 수도 있습니다. 또는 어느 시점에서 사용자 정의 처리를 수행하고 싶을 수도 있습니다. 심지어 Antora를 귀하의 요구에 맞게 재구성하기 위해 자신만의 동작을 도입할 수도 있습니다. Antora는 기본 제공 사이트 생성기가 적합하지 않을 때, 이를 기반으로 자신만의 사이트 생성기를 만들 수 있도록 설계되었습니다.