[spring-rest-docs] adoc 파일을 pdf로 저장하는 방법

spring-rest-docs를 적용해서 html로 API 문서를 공유하면 편하다. 하지만, 제출용으로 html 링크를 보낼 수 없는 관계로 pdf 형식으로 변경해야 했다. 

 

아래는 spring-rest-docs 를 적용하여, .adoc 파일이 다 만들어졌다는 가정하에, pdf 로 문서를 만드는 방법에 대해서 소개한다. 

 

 

spring-rest-docs 적용 링크는 아래를 참고해주세요~

[링크]

https://tbmaster.tistory.com/96

 

---

 

adoc  파일 -> pdf 변환 방법

$asciidoctor-pdf ./index.adoc -o ./publisher.pdf

명령어 asciidoctor-pdf 를 입력하고 변환하고자 하는 파일(index.adoc), 결과파일(publisher.pdf) 를 입력한다.

그러면, 결과는 현재위치(./) 에 publisher.pdf 파일이 생성됨을 확인할 수 있다.

 

 

asciidoctor-pdf  설치 방법

asciidoctor-pdf 는 Ruby로 되어 있어, ruby 를 설치해야 한다.

 

1. 아래 Ruby 사이트에서 RubyInstaller를 다운로드하여, 설치한다.

https://rubyinstaller.org/downloads/

Downloads

 

2. Ruby의 gem을 이용하여, asciidoctor-pdf 를 설치한다.

gem 명령은 설치한 Ruby 에서 bin 폴더로 이동하면, gem 파일이 있다. 해당 위치까지 이동하여 아래 명령어를 실행한다.

$gem install asciidoctor-pdf

[ asciidoctor-pdf 설치 예시 ]

설치가 완료되면, 아래와 같이 "asciidoctor-pdf -v" 을 이용해 버전 정보를 확인할 수 있다.

[ asciidoctor-pdf  버전 정보 확인 ]

 

 

설치가 완료되면, 위의 "adoc파일 -> pdf 변환방법" 을 진행하면 된다.

 

 

한글이 깨질 경우

adoc을 pdf로 변환 후, 한글이 네모박스로 표시되어 변환되었다. 아래와 같이 수정하여, 한글도 출력되도록 하자.

 

1. 한글 폰트를 찾아,  Ruby의 data/fonts 폴더에 넣는다. (나의 경우, Windows 에 있는 한글폰트 중 하나를 사용했다.)

[ Ruby의 한글 폰트 저장 경로 ]

 

2. Ruby의 themes 폴더에서 default-teme.yml에 추가한 한글 폰트로 시작하도록 값을 변경한다.

[ default-theme.yml 파일이 존재하는 경로 ]

 

default-theme.yml 파일을 열면 아래와 같은 내용이 나타나며, 한글 폰트를 아래와 같이 입력한다. 

Noto Serif 와 M+ 1mn 부분을 같이 변경해줘야, adoc의 box 내부 한글도 잘 변환된다.

[ default 폰트 변경 ]

 

3. 이후에 다시, "adoc 파일 -> pdf 변환방법"을 재실행한다.

 

 

참고

https://docs.asciidoctor.org/pdf-converter/latest/install/

Asciidoctor PDF - Install Asciidoctor PDF

https://docs.asciidoctor.org/pdf-converter/latest/convert-to-pdf/

Asciidoctor PDF - Convert AsciiDoc to PDF

https://wiznxt.tistory.com/857

Asciidoc adoc 파일 pdf 변환시 한글 폰트 해결 팁 (잔머리)