[linux] debian 12에서 wkhtmltopdf를 이용해 cli 환경에서 html을 pdf로 변환하기 (한글 깨짐 수정)

wkhtmltopdf란?

Webkit 엔진을 사용해 cli 환경에서 html을 pdf로 변환해 주는 오픈 소스 프로젝트.

wkhtmltopdf

처음에는 python의 pdfkit이라는 라이브러리를 사용하다가 알게 되었다.

pdfkit은 wkhtmltopdf를 python에서 사용할 수 있도록 해주는 라이브러리인데 사용에 제한이 있어 직접 라이브러리를 고쳐서 사용하다가 wkhtmltopdf만 따로 사용해 보니 훨씬 편하게 사용할 수 있었다.

 

설치

wget을 이용해 설치 파일을 다운로드해야 한다.

# wget 설치
sudo apt update
sudo apt install wget

# wkhtmltopdf 설치 파일 다운로드
wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-3/wkhtmltox_0.12.6.1-3.bookworm_amd64.deb

# 설치
sudo apt install ./wkhtmltox_0.12.6.1-3.bookworm_amd64.deb

wkhtmltopdf --version
# wkhtmltopdf 0.12.6.1 (with patched qt)

 

사용법

기본적인 사용법은 정말 간단하다. wkhtmltopdf를 호출하고 pdf로 변환할 html의 경로와 결과물의 경로를 적어주면 된다.

# html to pdf
wkhtmltopdf /home/pdf_test/test.html /home/pdf_test/output.pdf

# url to pdf
wkhtmltopdf google.com /home/pdf_test/output.pdf

 

파일 접근 권한

html이 파일을 사용해야 한다면 파일의 접근 권한 옵션을 줘야한다.

# 모든 파일에 접근 권한 주기
wkhtmltopdf --enable-local-file-access /home/pdf_test/test.html /home/pdf_test/output.pdf

# 특정 경로에 접근 권한 주기
wkhtmltopdf --disable-local-file-access --allow <path> /home/pdf_test/test.html /home/pdf_test/output.pdf

 

크기 맞춤

이미지 크기가 안맞는 경우가 있는데 이런 경우 마진을 주는 옵션을 주거나 자동으로 맞춰주는 옵션을 사용하면 된다.

# 왼쪽 오른쪽 마진
wkhtmltopdf -L 10 -R 10 /home/pdf_test/test.html /home/pdf_test/output.pdf

# 위 아래 마진
wkhtmltopdf -T 10 -B 10 /home/pdf_test/test.html /home/pdf_test/output.pdf

# 자동 맞춤
wkhtmltopdf --enable-smart-shrinkin /home/pdf_test/test.html /home/pdf_test/output.pdf
wkhtmltopdf --disable-smart-shrinkin /home/pdf_test/test.html /home/pdf_test/output.pdf

 

자바스크립트 사용

디폴트가 자바스크립트 사용 지원이지만 디버그 옵션이나 용량이 큰 자바스크립트 로딩을 위해 기다리는 시간을 설정하는 옵션을 사용할 수 있다.

# 디버그 옵션 사용
wkhtmltopdf --debug-javascript /home/pdf_test/test.html /home/pdf_test/output.pdf

# 딜레이 옵션 사용
wkhtmltopdf --javascript-delay 2000 /home/pdf_test/test.html /home/pdf_test/output.pdf

 

 

한글 깨짐

한글을 지원하지 않기 때문에 한글이 다 깨져서 출력된다.

이 문제는 한글 폰트를 설치하면 해결된다.

# 나눔 폰트 다운로드
wget http://static.campaign.naver.com/0/hangeul/renew/download/NanumFont_TTF.zip

# 압축 풀기
sudo apt install unzip
unzip NanumFont_TTF.zip

# 폰트 적용
mkdir /usr/share/fonts/nanumfont
mv NanumGothic.ttf /usr/share/fonts/nanumfont/
fc-cache

 

옵션