Asciidoctor 공식 가이드 및 테마 참조 링크

1. 마크다운(Markdown)의 한계와 Asciidoctor 도입

소프트웨어 아키텍처나 복잡한 API 스펙 문서를 작성할 때, 보통 가장 먼저 떠올리는 도구는 마크다운(Markdown)입니다. 하지만 마크다운은 치명적인 단점이 있습니다.

표준의 부재: GitHub Flavored, CommonMark 등 파서마다 지원하는 문법과 테이블 형태가 다릅니다.
복잡한 문서 구조화 불가: 목차(TOC) 생성, Include(다른 문서 파편 불러오기), 복잡한 표(Table) 병합, 각주, 레퍼런스 링크 처리가 파편화되어 있거나 불가능에 가깝습니다.
출판용 포맷팅 한계: PDF나 ePub 포맷으로 깔끔하게 변환하여 외부 고객사나 파트너에게 공식 문서로 납품하기가 매우 까다롭습니다.

이러한 마크다운의 한계를 극복하기 위해 실무 환경에서 시스템 매뉴얼이나 공식 사용자 가이드(User Guide)를 작성할 때 널리 쓰이는 강력한 대안이 바로 Asciidoctor(.adoc) 입니다.

2. Asciidoctor의 강력한 특징

Asciidoctor는 Ruby 환경에서 시작된 텍스트 프로세서로, AsciiDoc 포맷을 HTML5, PDF, EPUB 등 다양한 포맷으로 세련되게 변환해 줍니다. 대표적인 장점은 다음과 같습니다.

방대한 빌트인 문법: 경고창(Admonitions), 소스코드 하이라이팅, 복잡한 테이블, 수학 수식 등을 기본 문법으로 완벽하게 지원합니다.
문서 모듈화 (include): 장(Chapter)별로 쪼개진 여러 개의 .adoc 파일을 하나의 마스터 파일로 가져와 조립할 수 있습니다. 큰 규모의 책이나 매뉴얼을 협업해서 쓰기에 최적화되어 있습니다.
다양한 생태계 플러그인: PlantUML 등과 결합하여 텍스트만으로 다이어그램을 그려 넣을 수 있습니다.
강력한 PDF 테마링: YAML 기반의 테마 설정 파일을 통해, 생성되는 PDF의 폰트, 여백, 표지, 워터마크, 헤더/푸터 디자인을 개발자 친화적으로 커스터마이징 할 수 있습니다.

3. 핵심 레퍼런스와 매뉴얼 모음

초기 세팅이나 문법이 헷갈릴 때 가장 정확하고 빠르게 참고할 수 있는 필수 레퍼런스 링크들을 정리해 둡니다.

공식 홈페이지 (Official): Asciidoctor Website
상세 사용자 매뉴얼 (User Manual): Asciidoctor User Manual
- Tip: 문법이 막힐 때는 구글링보다 공식 매뉴얼 검색이 훨씬 빠르고 정확합니다.
Asciidoctor PDF 테마 및 스타일링 가이드: AsciiDoctor-PDF Theming Guide (GitHub)
- Tip: 회사 로고를 박고 자사 전용 폰트로 매뉴얼을 납품해야 할 때 필수적으로 봐야 하는 문서입니다.
오픈소스 리포지토리 (GitHub): Asciidoctor GitHub Organization
자바/스프링 환경 플러그인 (AsciidoctorJ PDF): Maven Repository
- Tip: Maven/Gradle 빌드 라이프사이클에 문서를 태워, 코드가 빌드될 때 공식 매뉴얼 PDF도 젠킨스(Jenkins)에서 함께 빌드되도록 파이프라인을 구축할 때 사용합니다.

4. 실무 적용 팁

팀 내에서 기술 문서를 표준화할 때 처음에는 “문법이 너무 많다”는 피드백이 있을 수 있습니다. 하지만 IDE(IntelliJ 등)에 AsciiDoc 플러그인을 설치하면 우측에 실시간 프리뷰가 제공되므로 허들이 금방 낮아집니다.

특히 CI/CD 빌드 파이프라인에 Asciidoctor 플러그인을 태워, 소스코드가 머지될 때마다 최신화된 PDF 매뉴얼이 산출물(Artifact) 서버에 떨어지도록 구성하면, 문서 팀과 개발 팀의 싱크를 강제로 맞추는 아주 훌륭한 “Docs-as-Code” 환경을 구축할 수 있습니다.