HTML PDF 변환

페이지가 접근할 수 있는 것, 그리고 CSS가 좌우하는 것

변환 과정은 네트워크에 접근하지 않고 스크립트도 실행하지 않습니다. 둘 다 빠진 기능이 아니라 보안상의 결정입니다. 제출된 페이지가 요청하는 것을 무엇이든 불러오는 변환기는 저희 서버만 볼 수 있는 주소를 향하도록 악용될 수 있고, 스크립트를 실행하는 변환기는 낯선 사람의 코드를 돌리는 셈입니다. 그래서 CDN에 연결된 스타일시트는 불러와지지 않고, 일반 웹 주소의 이미지는 로드되지 않으며, 웹 글꼴은 조용히 대체되고, JavaScript로 스스로를 그리는 페이지는 아무것도 실행되기 전의 마크업 상태로 변환됩니다. 해결책은 늘 같습니다. CSS는 style 블록에 인라인으로 넣고 이미지는 data URI로 내장하세요. 브라우저에서 바로 할 수 있습니다. Firefox의 “다른 이름으로 페이지 저장 → 웹 페이지, 전체”나 “MHTML로 저장”을 쓰면 되고, 이렇게 저장한 단일 파일 페이지는 충실하게 변환됩니다.

두 번째로 알아 둘 점은 결과를 실제로 좌우하는 것이 인쇄용 CSS라는 것입니다. 페이지는 인쇄하는 것처럼 배치되므로 @media print 블록이 적용되고, 일반 화면용 스타일시트는 적용되지 않을 수 있습니다. 그래서 내비게이션을 숨기는 인쇄 규칙이 있는 페이지는 깔끔하게 변환되고, 그런 규칙이 없는 페이지는 사이트의 메뉴와 틀까지 통째로 딸려 옵니다. 용지는 @page가 정합니다. 크기, 방향, 여백을 여기서 읽습니다. 페이지가 나뉘는 위치는 break-before, break-after, break-inside: avoid가 결정하므로, 나뉘면 안 되는 표나 새 페이지에서 시작해야 하는 섹션도 전적으로 직접 제어할 수 있습니다.

배경은 대표적으로 빠지기 쉬운 부분입니다. 브라우저는 기본적으로 배경색과 배경 이미지를 인쇄하지 않으므로, 스타일시트에 -webkit-print-color-adjust: exact가 없으면 어두운 머리글이 흰색으로 변환될 수 있습니다. 단 한 줄이지만, 브랜드가 살아 있는 문서와 밋밋한 문서를 가르는 차이입니다. 텍스트는 실제 텍스트로, 링크는 작동하는 링크로 남고, 마크업이 진짜 제목 요소를 사용한 곳에서는 제목이 PDF 책갈피가 될 수 있습니다.

서버에 연결할 수 없으면 페이지에서 그 사실을 알리고 문서를 기기에서 직접 다시 만듭니다. 이때 텍스트, 이미지, 단순한 레이아웃은 유지하지만, grid, flexbox, float, 위치 지정처럼 실제 레이아웃 계산이 필요한 것은 단순화합니다. 단순한 문서는 거의 똑같이 변환되지만, 디자인된 문서는 그렇지 않습니다.

다른 작업이 필요할 때

이 페이지가 일부러 할 수 없게 막아 둔 실제 URL 변환은, 저희 서버에서 돌아가는 것과 같은 렌더링을 사용자의 컴퓨터에서 실행하면 됩니다. chrome --headless --disable-gpu --print-to-pdf=out.pdf https://example.com은 네트워크와 스크립트가 살아 있는 상태로 페이지를 불러옵니다. 차이는 그것뿐이며, 바로 그 이유로 이 방법을 쓰게 됩니다.

머리글, 바닥글, 페이지 번호, 여백을 제대로 제어하고 싶다면 WeasyPrint와 Prince가 CSS Paged Media 규격을 제대로 구현합니다. @top-center로 만드는 반복 머리글, 페이지 카운터, 각주, 페이지 번호로 연결되는 상호 참조까지 가능합니다. WeasyPrint는 무료이며 대부분의 문서화 파이프라인이 사용합니다. Chrome은 이 중 거의 아무것도 지원하지 않으므로, 바닥글에 “12페이지 중 3페이지”가 들어가는 보고서를 만들려면 이 도구가 아니라 둘 중 하나가 필요합니다.