since 2019.

1 minute read

Updated:

👩🏻‍💻 Asciidoc adoc 파일을 pdf로 변환하는 방법을 알아봅니다.

Spring REST Docs로 API 스펙 문서를 html로 생성했다. 해당 프로젝트를 배포한 상태가 아니므로 로컬 구동 시에만 확인이 가능한대 이 문서를 public하게 오픈하고 싶었다.
이런 저런 변환 방법을 알아보던 중 adoc 파일을 html 뿐아니라 pdf로도 생성할 수 있다고 해서 방법을 찾아보았고 아래와 같은 과정을 통해 API 스펙 문서를 pdf로 만들 수 있었다.

ruby 언어로 asciidoctor 설치하기

1. ruby 설치

asciidoctor 는 루비언어로 작성되어 있어, 실행하기 위해서는 루비가 설치되어 있어야 한다. 난 이미 루비가 설치된 상태라서 버전 확인만 했다.

apt-get install ruby
ruby -v //루비 버전 확인 명령어

2. asciidoctor 설치

gem install asciidoctor

3. asciidoctor-pdf 설치

gem install asciidoctor-pdf

4. asciidoctor-pdf-cjk-kai_gen_gothic 설치

asciidoctor-pdf 만 이용해서 PDF를 만들면 한글이 제대로 출력되지 않는다. asciidoctor-pdf 에서 사용할 폰트 gem 을 추가로 설치해야 한다.

gem install asciidoctor-pdf-cjk-kai_gen_gothic

5. asciidoctor-pdf-cjk-kai_gen_gothic 설치

나의 경우 이 명령어로 설치가 되지 않았다.

[1/20] Downloading KaiGenGothicCN-Bold-Italic.ttf
C:/Ruby27/lib/ruby/gems/2.7.0/gems/asciidoctor-pdf-cjk-kai_gen_gothic-0.1.1/exe/asciidoctor-pdf-cjk-kai_gen_gothic-install:34: warning: calling URI.open via Kernel#open is deprecated, call URI.open directly or use URI#open

warning: calling URI.open via Kernel#open is deprecated, call URI.open directly or use URI#open 이 부분이 원인인 듯한대 해결 방법을 찾지 못했다. 근본적으로 한글 폰트가 없는 것이 문제이므로 번거롭지만 폰트를 추가하고 적용하기로 했다.

트러블 슈팅 1 - 경로를 찾지 못하는 문제

PS C:\Work\work-board-project\src\docs\asciidoc> asciidoctor-pdf index.adoc
asciidoctor: ERROR: index.adoc: line 22: include file not found: C:/Work/work-board-project/src/docs/asciidoc/{snippets}/articles/httpie-request.adoc

경로를 찾지 못해 발생한 에러. {snippets}를 C:\Work\work-board-project\build\generated-snippets로 정확한 경로로 변경하였다.

트러블 슈팅 2 - pdf 한글이 깨지는 문제

  1. 한글폰트.ttf 파일 다운로드 후 C:\Ruby27\lib\ruby\gems\2.7.0\gems\asciidoctor-pdf-2.3.9\data\fonts 해당 경로에 추가하기

  2. C:\Ruby27\lib\ruby\gems\2.7.0\gems\asciidoctor-pdf-2.3.9\data\themes\default-theme.yaml 파일에 추가한 폰트로 적용 
    font:
  catalog:
 # Noto Serif supports Latin, Latin-1 Supplement, Latin Extended-A, Greek, Cyrillic, Vietnamese & an assortment of symbols
 Noto Serif:
   //수정 시작
   normal: NanumGothic.ttf
   bold: NanumGothicBold.ttf
   italic: NanumGothicExtraBold.ttf
   bold_italic: NanumGothicLight.ttf
   //수정 끝
  3. asciidoctor-pdf index.adoc 명령어로 pdf 생성 실행

You may also enjoy