--- name: modu-ai/pdf-writer source: https://app.decimal.ai/s/modu-ai-pdf-writer@1/SKILL.md source_sha256: 0fa11d22ee2e --- # PDF 생성기 (pdf-writer) ## 개요 **weasyprint 단일 엔진**으로 모든 입력을 PDF로 렌더합니다. 입력 형태와 무관하게 `입력 → HTML → weasyprint → PDF` 한 경로로 통일되어, 다음 두 시나리오를 모두 충실히 처리합니다. 1. **스타일이 입혀진 HTML 리포트** (예: `moai-content:html-report`·`moai-content: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. [폰트 확인] → assets/fonts/ 에 Noto Sans CJK OTF 4종 존재 확인, 누락 시 download_fonts.py 자동 호출 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 표시·플레이스홀더 잔존) ``` 핵심 실행은 번들 스크립트 한 줄로 끝납니다: ```bash # HTML 리포트를 디자인 그대로 PDF로 (가장 흔한 케이스) python3 moai-office/skills/pdf-writer/scripts/render_pdf.py --in report.html --out report.pdf # Markdown / JSON / Text → PDF python3 moai-office/skills/pdf-writer/scripts/render_pdf.py --in doc.md --out doc.pdf python3 moai-office/skills/pdf-writer/scripts/render_pdf.py --in data.json --out doc.pdf ``` `scripts/render_pdf.py`가 입력 종류를 자동 감지하고, 완성 HTML은 자체 CSS를 보존한 채 렌더하며, Markdown/JSON/Text는 기본 서식 + Noto Sans CJK를 적용합니다. ### 0단계: 폰트 자동 보장 (스킬 진입점) ```python import subprocess, sys from pathlib import Path SKILL_ROOT = Path(__file__).parent DOWNLOADER = SKILL_ROOT / "scripts" / "download_fonts.py" def ensure_fonts(): """Noto Sans CJK OTF 4종 존재 검증, 누락 시 자동 다운로드.""" if subprocess.run([sys.executable, str(DOWNLOADER), "--check"]).returncode != 0: if subprocess.run([sys.executable, str(DOWNLOADER)]).returncode != 0: raise RuntimeError("Noto Sans CJK 폰트 다운로드 실패. 네트워크/GitHub 접근 확인 필요.") ensure_fonts() # PDF 생성 직전 호출 ``` 다운로드는 최초 1회(약 64MB)만 발생하며, 이후 `--check`가 즉시 통과합니다. 시스템에 `Noto Sans CJK KR`이 이미 있으면 폰트가 없어도 weasyprint가 자동 폴백하므로 CJK는 안전하게 표시됩니다. ### 1~4단계: weasyprint 렌더링 핵심 코드 `scripts/render_pdf.py`의 핵심은 다음과 같습니다 (전체 구현은 스크립트 참조): ```python from weasyprint import HTML, CSS from pathlib import Path FONT_DIR = Path("moai-office/skills/pdf-writer/assets/fonts") # 번들 Noto Sans CJK를 @font-face로 등록 (weight별) FONT_FACE = "".join( f"@font-face{{font-family:'Noto Sans CJK';font-weight:{w};" f"src:url('file://{FONT_DIR}/NotoSansCJK-{n}.otf');}}" for w, n in {300: "Light", 400: "Regular", 500: "Medium", 700: "Bold"}.items() if (FONT_DIR / f"NotoSansCJK-{n}.otf").exists() ) # (A) 완성 스타일 HTML → 자체 CSS 보존, CJK 폰트만 보강 HTML(string=styled_html, base_url=".").write_pdf("out.pdf", stylesheets=[CSS(string=FONT_FACE)]) # (B) Markdown/JSON/Text에서 만든 HTML → 기본 문서 CSS + 폰트 HTML(string=plain_html, base_url=".").write_pdf("out.pdf", stylesheets=[CSS(string=FONT_FACE + BASE_CSS)]) ``` `BASE_CSS`는 `@page { size:A4; margin:20mm }` + 본문/제목/표 스타일로, `font-family`에 `'Noto Sans CJK'`를 지정해 CJK가 항상 임베딩 폰트로 렌더되게 합니다. ## 의존성 ```bash pip install weasyprint # 핵심 렌더링 엔진 (풀 CSS → PDF) pip install markdown # Markdown → HTML 변환 (선택, 없으면 최소 폴백) ``` > weasyprint는 시스템 라이브러리 `cairo` / `pango` / `gdk-pixbuf`를 사용합니다. 대부분의 > Cowork 샌드박스 및 Linux/macOS 환경에 기본 포함돼 있어 `pip install weasyprint`만으로 동작합니다. ## 입력 포맷 명세 ### 완성 HTML (디자인 보존) ``·``·`` 신호가 있으면 **완성 문서로 간주**하여 자체 `