HTML을 PDF로: 생각보다 어려워

멋진 웹 페이지가 있어. PDF로 필요해. Control+P, PDF로 저장. 끝?

때론 그래. 하지만 종종 결과엔 깨진 레이아웃, 빠진 이미지, 이상한 페이지 나누기, 문장 중간에 잘린 헤더가 있어.

HTML과 PDF는 근본적으로 달라. 함께 작동하게 만들려면 노력이 필요해.

왜 복잡한가

HTML은 유동적이야. 콘텐츠가 사용 가능한 공간을 채우려고 흘러. 반응형. 유연해.

PDF는 고정돼. 특정 페이지 치수. 정확한 위치. 아무것도 흐르지 않아.

변환은 적응하도록 설계된 걸 가져다가 고정된 페이지에 강제로 넣는다는 뜻이야.

페이지 나누기가 적

아름다운 문단이 두 페이지에 걸쳐 나뉘어. 테이블 헤더는 페이지 3에, 데이터는 페이지 4에서 시작해.

CSS에 page-break-before, page-break-after, page-break-inside 속성이 있어. 이걸 제어해야 해.

h2 {
  page-break-after: avoid;
}

table {
  page-break-inside: avoid;
}

"해야 한다"는 건 브라우저 지원이 다양하기 때문이야. 철저히 테스트해.

뭐가 렌더링되고 뭐가 안 되는지

웹 폰트: 때론 작동하고, 때론 안 해. 폴백이 아니라 실제 폰트로 테스트해.

배경색: 종종 기본적으로 제외돼 (잉크 절약). "배경 인쇄" 설정 확인해.

이미지: 외부 이미지가 로드되지 않을 수 있어. 변환 시점에 CORS 문제가 나타나.

JavaScript로 렌더링된 콘텐츠: 콘텐츠가 JS로 로드되면 PDF가 페이지를 캡처할 때 존재하지 않을 수 있어.

애니메이션과 전환: 사라져. PDF는 정적이야.

Print 스타일시트

CSS에 print용 미디어 타입이 있어:

@media print {
  .no-print {
    display: none;
  }

  body {
    font-size: 12pt;
  }

  a::after {
    content: " (" attr(href) ")";
  }
}

네비게이션 숨기고, 폰트 조정하고, 링크 URL 표시. 인쇄 출력을 위해 특별히 디자인해.

다른 변환 방법들

브라우저 print to PDF: 일회성 변환에 좋아. 결과가 브라우저마다 다양해.

헤드리스 브라우저 (Puppeteer, Playwright): 프로그래밍 제어. 일관된 결과. 설정 필요.

PDF 라이브러리 (wkhtmltopdf, WeasyPrint): 전용 도구. 출력에 대한 더 나은 제어.

온라인 서비스: HTML 업로드, PDF 받기. 가끔 사용에 편리.

각각 품질, 속도, 제어에 트레이드오프가 있어.

더 나은 결과를 위한 팁

고정 너비 써. 반응형 레이아웃은 예측 불가능한 결과를 만들어. PDF 출력을 위해 특정 너비 설정.

레이아웃 단순화. 복잡한 CSS grid랑 flexbox는 깨질 수 있어. 더 간단한 레이아웃이 더 확실하게 변환돼.

폰트 임베드. 시스템 폰트가 사용 가능하다고 의존하지 마.

일찍 테스트. 전체 페이지를 만들고 나서 PDF 변환을 시도하지 마. 만들면서 테스트해.

명시적 페이지 크기 설정. PDF는 페이지 단위로 생각해. 크기를 알려줘.

@page {
  size: A4;
  margin: 1cm;
}

네이티브 PDF를 써야 할 때

정확한 제어가 필요하면—계약서, 송장, 정확한 포맷팅이 있는 보고서—HTML 변환 대신 PDF를 직접 생성하는 걸 고려해.

PDFKit, ReportLab, iText 같은 라이브러리는 HTML 변환 레이어 없이 PDF를 만들어.

더 많은 작업, 더 많은 제어, 더 예측 가능한 결과.

---

HTML에서 PDF로 변환은 작동하지만, print 스타일, 페이지 나누기, 웹과 인쇄 매체 간 차이에 주의가 필요해. 철저히 테스트하고 기대를 적절히 설정해.