doc-pdf

PDF 생성기 (doc-pdf)

개요

weasyprint 단일 엔진으로 모든 입력을 PDF로 렌더합니다. 입력 형태와 무관하게 입력 → HTML → weasyprint → PDF 한 경로로 통일되어, 다음 두 시나리오를 모두 충실히 처리합니다.

1. 스타일이 입혀진 HTML 리포트 (예: moai-officer:doc-html-report·moai-officer:doc-html-slide 산출물, 또는 사용자가 만든 디자인 HTML) → 자체 CSS를 그대로 렌더해 화면 디자인을 보존합니다. 2열 카드 그리드·커스텀 색·웹폰트 등 모던 CSS 레이아웃이 깨지지 않습니다.
2. Markdown · 구조화 JSON · 일반 텍스트 → 기본 문서 서식(A4·표·제목 스타일)을 적용해 렌더합니다.

CJK(한·중·일) 글리프는 번들 Noto Sans CJK 폰트를 @font-face로 임베딩해 깨짐을 차단하며, 시스템에 Noto Sans CJK KR이 설치돼 있으면 fontconfig가 자동 폴백합니다.

왜 weasyprint 단일 엔진인가: weasyprint는 풀 CSS(레이아웃·색·웹폰트·표)를 충실히 렌더합니다. "이 HTML 리포트를 디자인 그대로 PDF로"가 가장 흔한 요청이며, 이 경로가 그 요구를 정확히 만족합니다. 좌표 기반 저수준 렌더링(예: PyMuPDF insert_text)은 모던 CSS 레이아웃을 재현하지 못하므로 사용하지 않습니다.

워크플로우

0. [폰트 확인]  → 시스템 Noto Sans CJK KR 존재 확인, 없으면 폰트 미지정 폴백 (weasyprint fontconfig 자동 폴백)
1. [입력 감지]  → HTML(완성 문서) / Markdown / JSON / Text 자동 감지
2. [HTML 빌드]  → 완성 HTML은 그대로, 그 외는 HTML로 변환 (+ 기본 문서 CSS)
3. [폰트 주입]  → Noto Sans CJK @font-face CSS 결합 (CJK 깨짐 방지)
4. [렌더]       → weasyprint HTML.write_pdf() 로 A4 PDF 생성
5. [자체 검수]  → 산출 PDF 재확인 (페이지 수·CJK 표시·플레이스홀더 잔존)

핵심 실행은 아래 인라인 weasyprint 코드로 직접 수행합니다(별도 스크립트 없음). 입력 파일 확장자·내용으로 HTML / Markdown / JSON / Text를 감지해 분기하고, 완성 HTML은 자체 CSS를 보존한 채, 그 외는 기본 서식 + Noto Sans CJK를 적용합니다.

0단계: 폰트 보장 (조건부 경로)

CJK 폰트는 다음 우선순위로 해결합니다 — 별도 다운로드 스크립트 없이:

1. 시스템 폰트 우선: 시스템에 Noto Sans CJK KR이 설치돼 있으면 weasyprint fontconfig가 자동 폴백하므로 @font-face 없이도 CJK가 안전하게 표시됩니다. 대부분의 Cowork 샌드박스·Linux/macOS가 이에 해당합니다.

2. 번들 폰트가 있으면 임베딩: ${CLAUDE_PLUGIN_ROOT}/skills/doc-pdf/assets/fonts/에 Noto Sans CJK OTF가 있으면 아래 코드의 @font-face가 자동으로 임베딩합니다(있으면 사용, 없으면 1번 폴백).

3. 둘 다 없을 때: 사용자에게 시스템 Noto Sans CJK KR 설치를 안내합니다. 운영체제별 명령은 아래와 같으며, 자동 대량 다운로드는 수행하지 않습니다.

   OS	설치
   Windows	fonts.google.com/noto/specimen/Noto+Sans+KR에서 받아 압축 해제 → 폰트 파일 전체 선택 → 우클릭 → 설치
   macOS	brew install --cask font-noto-sans-cjk-kr
   Debian/Ubuntu	apt install fonts-noto-cjk