book-pdf-pagedjs

마크다운 → 진짜 책 PDF/EPUB

일반 page.pdf() + 마크다운→HTML 변환만으로는 "리포트를 인쇄한 것"처럼 보인다. 실제 책이려면 최소 이 6가지가 있어야 한다: 표지(풀블리드) · 타이틀 페이지 · 판권 페이지 · 실제 쪽번호가 달린 목차 · 장 시작마다 새 페이지 · 쪽마다 러닝헤더/쪽번호.

이 스킬은 Paged.js(MIT, https://unpkg.com/pagedjs/dist/paged.polyfill.js)를 브라우저에 스크립트 태그로 로드해 CSS Paged Media 기능(러닝헤더, 목차 쪽번호 자동생성)을 구현한다. Chromium이 네이티브로 지원 안 하는 기능이라 이 폴리필이 필요하다.

이 환경(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 문자열 안에 <script src="https://unpkg.com/..."> 태그를 직접 넣어야 로드된다.
4. 구글 폰트 @import/<link>가 document.write() 직후엔 타이밍 문제로 반영 안 될 때가 있다. 커스텀 세리프 폰트를 꼭 써야 하면 woff2를 직접 fetch해서 base64로 인라인 @font-face에 박아넣을 것. 급하면 시스템 폰트(-apple-system, 'Apple SD Gothic Neo')로 타협.
5. target-counter()로 목차 쪽번호를 만들 때 한글 슬러그 id가 깨질 수 있다. pandoc이 자동 생성하는 id="1장-시작과-실패" 같은 한글 id 대신 ch-01, part-1, app-a 같은 ASCII id로 바꿔서 앵커를 걸 것.
6. CSS page: (named page) 속성을 제목 요소에만 주고 바로 다음 형제 요소에는 안 주면, 그 둘 사이에 강제 페이지베이크가 생긴다. 단순히 break-before: page로 장/부 시작만 제어하고 싶을 때는 page: main; 같은 명명 페이지 지정을 쓰지 말거나, 쓴다면 본문 전체에 동일하게 적용해야 한다 — 이건 "장 제목 바로 뒤에 이미지를 넣었는데 이미지가 다음 페이지로 밀리며 압도적인 빈 공백 페이지가 생기는" 증상으로 나타난다. 페이지 구성이 이상하면 가장 먼저 이 속성부터 의심할 것.
7. 트림 사이즈로 A5(148x210mm)를 쓰지 말 것. A5와 A4는 비율이 동일해(1:1.414, ISO 시리즈) 화면에서 보면 "작은 A4 문서"처럼 보인다. 한국 단행본 표준판형인 **신국판(152x225mm, 비율 1:1.48)**을 쓰면 "진짜 책" 느낌이 명확하게 산다.
8. Paged.js 렌더링은 비동기라 완료 시점을 폴링해야 한다. document.querySelectorAll('.pagedjs_page').length가 N초 연속 안 바뀔 때까지 기다린 다음 page.pdf()를 호출할 것. 문서가 크면(80150쪽) 완료까지 30초1분 걸릴 수 있다.
9. page.pdf()는 가로 flexbox를 통째로 날려버린다. display:flex로 카드 3장을 나란히 놓으면 화면(스크린샷)에서는 멀쩡한데 PDF 출력에서는 그 영역이 통째로 빈칸으로 나온다. 세로 방향(flex-direction:column)은 정상. <table>로 바꿔도 안 되니, 가로 배치가 필요하면 **display:inline-block + vertical-align:middle**로 짤 것. 이건 Paged.js와 무관하게 일반 page.pdf()에서도 발생한다.
10. page.screenshot({clip})은 뷰포트(1440x900)를 넘는 영역을 못 찍는다. 세로 1600px짜리 썸네일을 clip으로 찍으면 900px 아래는 잘리고, 여러 번 찍으면 같은 이미지가 반복되거나 내용이 누락된다. setViewportSize()도 없으므로(함정 2), 큰 이미지는 무조건 page.pdf() + pdftoppm 경유로 만든다.
11. document.write()를 반복 호출하면 이전 문서가 남아 중복 렌더링된다. 한 탭에서 여러 이미지를 연속으로 뽑을 때 결과물이 세로로 두 번 반복되거나 MD5가 전부 동일하게 나오면 이 증상이다. HTML을 파일로 쓰고 page.goto('file://<절대경로>')로 여는 방식이 안전하다 — file://은 이 환경에서 정상 동작하고, 매번 완전히 새 문서가 로드된다.
12. document.write()로 넣은 스크립트에서 top-level const로 선언한 값이 나중 스크립트에서 안 보일 때가 있다. 렌더 함수를 window.render처럼 전역에 붙여도 데이터가 undefined로 잡히면, 스크립트를 쪼개지 말고 변형별로 완성된 HTML을 통째로 만들어 각각 파일로 저장할 것.