# Book PDF > 마크다운 원고를 진짜 책처럼 보이는 PDF·EPUB 전자책으로 만든다. 표지, 판권 페이지, 실제 쪽번호가 달린 목차, 장별 러닝헤더까지 갖춘다. Paged.js 사용. - Skill: `bam-bam-2/book-pdf` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add bam-bam-2/book-pdf` - Raw SKILL.md: https://api.skillmd.com/api/skills/bam-bam-2/book-pdf/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: bam-bam-2 (https://skillmd.com/u/bam-bam-2) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/bam-bam-2/book-pdf --- # 마크다운 → 진짜 책 PDF/EPUB 일반 `page.pdf()` + 마크다운→HTML 변환만으로는 "리포트를 인쇄한 것"처럼 보인다. 실제 책이려면 최소 이 6가지가 있어야 한다: **표지(풀블리드) · 타이틀 페이지 · 판권 페이지 · 실제 쪽번호가 달린 목차 · 장 시작마다 새 페이지 · 쪽마다 러닝헤더/쪽번호**. 이 스킬은 [Paged.js](https://pagedjs.org)(MIT, `https://unpkg.com/pagedjs/dist/paged.polyfill.js`)를 브라우저에 스크립트 태그로 로드해 CSS Paged Media 기능(러닝헤더, 목차 쪽번호 자동생성)을 구현한다. Chromium이 네이티브로 지원 안 하는 기능이라 이 폴리필이 필요하다. ## 바로 쓰는 스크립트 [`scripts/html-to-pdf.py`](scripts/html-to-pdf.py) — Paged.js로 조판한 HTML을 PDF로 굽습니다. ```bash pip install playwright && playwright install chromium python scripts/html-to-pdf.py book.html python scripts/html-to-pdf.py "chapters/*.html" # 여러 개 한 번에 ``` `--output`으로 경로를 지정할 수 있고, 생략하면 입력 파일명 그대로 `.pdf`가 나옵니다. ## 이 환경(Aside REPL)의 알려진 함정 1. **`page.pdf({width, height})` 파라미터가 무시된다.** 항상 US Letter로 나온다. 반드시 `preferCSSPageSize: true`를 주고 CSS `@page { size: 148mm 210mm; }`로 크기를 지정할 것. `format: 'A5'` 같은 심볼릭 사이즈도 마찬가지로 무시되니 쓰지 말 것. 2. **`page.setViewportSize()`가 없다.** 뷰포트 크기를 못 바꾸므로 표지 등 개별 이미지를 만들 때 `page.screenshot({fullPage:true})`로 큰 캔버스를 찍으면 타일링 버그가 난다. 대신 `page.pdf()` + `pdftoppm`으로 원하는 크기를 렌더링할 것. 3. **`page.addScriptTag()`가 없다.** 외부 스크립트(Paged.js 등)는 `document.write()`로 쓰는 HTML 문자열 안에 ` ${frontMatter}${bodyContent}`; await page.evaluate((h) => { document.open(); document.write(h); document.close(); }, html); // 안정화 폴링 let last = -1, stable = 0; for (let i = 0; i < 60; i++) { await sleep(1000); const n = await page.evaluate(() => document.querySelectorAll('.pagedjs_page').length); if (n === last) { if (++stable >= 3) break; } else stable = 0; last = n; } const pdf = await page.pdf({ printBackground: true, preferCSSPageSize: true }); ``` 7. **검수는 `aside.pdf.renderPages()`로 표지/타이틀/판권/목차/본문 몇 쪽을 실제로 렌더링해서 눈으로 확인**한다. `pdfinfo`로 최종 `Page size`가 의도한 트림 사이즈(A5 등)인지 꼭 재확인한다 (함정 1번 재발 여부 체크). 8. **EPUB은 별도로 pandoc이 이미 잘 만든다**: `pandoc manuscript.md -t epub3 --css=epub.css --epub-cover-image=cover.jpg --toc --toc-depth=2 -o book.epub`. EPUB은 리플로우 포맷이라 쪽번호/러닝헤더 개념이 없고 nav.xhtml 목차만 있으면 충분하다. ## 어색한 쪽 분리(내용이 잘려서 다음 페이지로 넘어가는 현상) 방지 표/인용문/코드블록이 문장 중간에서 맥려서 다음 페이지로 이어지는 건 CSS에 깨짐 방지 규칙이 없어서다. 다음을 기본값으로 넣을 것: ```css p { orphans: 3; widows: 3; } table, blockquote, pre, img, figure { break-inside: avoid; page-break-inside: avoid; } h2, h3 { break-after: avoid; page-break-after: avoid; } /* 소제목이 페이지 맨아래 혼자 남지 않게 */ ``` 이렇게 하면 문단/표/인용문이 한 페이지에 다 안 들어갈 때 그 블록 전체가 다음 페이지로 밀린다(사용자가 "앞 단락을 뒤로 밀어버려라"라고 표현하는 바로 그 동작). 부작용으로 강제 페이지보맜(장 시작 직전) 앞에 짧은 내용만 단독으로 낙은 거의-빈 페이지가 가끔 생기는데, 이건 실제 책에서도 흔한 자연스러운 현상이라 문제가 아니다. 적용 후반드시 **처음부터 끝까지 순차적으로 모든 페이지를 렌더링해서 육안으로 확인**할 것 — 하나만 집어서 보고 넘어가면 높은 확률로 놓친다. ## flexbox를 부/장 오프너에 쓰지 말 것 제목+삽화를 한 덩어리로 묶어서 같은 페이지에 있게 하려고 `display:flex`를 쓨다면, Paged.js가 flex 컨테이너 내부 높이 계산을 제대로 못 해서 **예상과 달리 자식 요소가 다음 페이지로 통째로 밀려나간다** (제목만 남고 삽화는 혼자 다음 장으로 가는 식). 한 페이지에 여러 요소를 묶을 때는 **평범한 블록 흐름(margin/padding)만으로** 레이아웃하고 flexbox/grid는 피할 것. 또한 제목과 그 바로 뒤에 오는 이미지 문단을 따로 처리하지 말고, 한 번의 정규식으로 단락(제목 헤딩 + 바로 뒤 이미지 단락)을 함께 매칭해서 **하나의 div로 합쳐넣으면** 둘이 한 덩어리로 취급되어 분리될 확률이 줄어든다. ## 스타일 참고 색은 절제된 포인트 컬러 1개(골드/앰버 등)만 쓰고, 여백을 넉넉히 준다. 장 오프너는 "CH.01" 같은 뱃지 + 큰 제목, 인용구는 왼쪽 세로선 + 이탤릭으로 처리하면 무난하게 "책스럽다".