AsciiDoc 문서와 Asciidoctor 참고 자료

AsciiDoc 문서를 작성하면서 찾아볼 자료를 모아 둔 메모입니다. 문법을 확인할 때와 PDF 출력 모양을 바꿀 때, Java 빌드에 연결할 때 참고할 곳이 서로 달라 나눠 정리했습니다.

AsciiDoc과 Asciidoctor

AsciiDoc은 문서를 작성하는 형식이고 Asciidoctor는 그 문서를 읽어 HTML 등으로 변환하는 도구입니다. .adoc 파일을 쓴다는 것과 어떤 변환기를 사용하는지는 구분해서 보면 좋습니다.

목차와 표, 문서 포함 같은 기능을 확인하려면 문법 문서를, 실행 옵션과 변환 과정을 보려면 Asciidoctor 문서를 찾을 수 있습니다.

PDF에는 별도 converter와 테마 설정이 있습니다. 본문 내용과 글꼴·여백·머리말 같은 출력 설정을 나눠 관리할 수 있습니다.

테마는 YAML로 정의합니다. 웹의 CSS와 역할이 비슷해 보여도 같은 속성과 문법을 그대로 사용하는 것은 아닙니다. 사용 중인 PDF converter 버전의 테마 문서를 확인해야 합니다.

JVM에서 Asciidoctor를 사용하려면 AsciidoctorJ와 관련 빌드 도구를 확인할 수 있습니다. Maven·Gradle에 문서 빌드를 연결할 때는 변환기와 플러그인의 역할을 구분해야 합니다.

문서 빌드가 성공했더라도 한글 글꼴과 표, 페이지 나눔 같은 출력은 결과 파일에서 확인해야 합니다. 내용의 정확성과 출력 형식은 따로 살펴볼 부분입니다.