원고 작성을 마크다운으로 완료한 후, 이를 보기 좋은 PDF 책으로 출판하기 위한 작업에 착수했습니다. 파이프라인 자체는 Python의 markdown 라이브러리와 pymdown-extensions 확장 패키지를 활용해 HTML을 먼저 생성한 다음, Playwright(Chromium)를 구동하여 PDF로 뽑아내는 방식으로 구축했습니다. 툴을 만드는 것까지는 일사천리로 진행되었지만, 진짜 난관은 바로 출력물 형태를 다듬는 인쇄 조판 작업이었습니다.
단순히 마크다운 PDF 변환 처리를 실행하는 것에 그치지 않고, 책 형태의 다듬어진 완성도를 얻기 위해서는 디테일한 CSS 인쇄 스타일 적용이 필수적이었습니다. 이 과정에서 발생한 수많은 레이아웃 깨짐 현상과 싸우며 고군분투한 경험을 정리해보았습니다.
마크다운에서 Playwright PDF로 이어지는 변환 파이프라인
기본적인 변환 흐름은 간단했습니다. 텍스트 원고에 포함된 체크리스트와 각종 특수 구문을 지원하기 위해 Python markdown 라이브러리에 pymdown-extensions 확장 모듈을 붙여 HTML 파일로 변환했습니다. 그 후 Headless 브라우저를 컨트롤하는 Playwright PDF 변환 기능을 호출해 웹 화면을 그대로 인쇄하듯 결과물을 생성했습니다.
하지만 브라우저 화면에서 깔끔하게 보이던 화면이 PDF로 인쇄 조판을 거치자 수많은 레이아웃 왜곡을 일으키기 시작했습니다. 화면상에서는 전혀 문제가 없던 요소들이 페이지 경계선에 걸치면서 심각한 조판 버그를 드러냈습니다.
페이지 넘김 시 배경이 깨지는 box-decoration-break 해결
가장 먼저 직면한 큰 문제는 페이지가 넘어갈 때 박스 요소의 좌우 배경색이 날아가고 뜬금없는 흰 여백이 노출되는 현상이었습니다. 문서가 여러 페이지에 걸쳐 인쇄되면서 첫 페이지 이후의 요소에서 스타일 연쇄가 끊기는 것이 원인이었습니다.
이 문제는 CSS 속성인 box-decoration-break: clone을 선언해주면서 깨끗하게 해결되었습니다. 속성을 적용하자 모든 페이지 경계마다 박스의 배경색과 패딩이 동일하게 반복 복사되어 들어가면서 매끄러운 디자인을 유지할 수 있었습니다.
또한 원고의 흐름상 특정 소제목이 항상 새로운 페이지 상단에서 시작되도록 강제할 필요가 있었습니다. 이를 위해 원하는 소제목 위치 앞에 직접 작성한 커스텀 마커를 배치하고, 페이지 전환 규칙을 적용해 원하는 위치에서 깔끔하게 단락이 넘어가도록 설정했습니다.
체크리스트와 비교표 조판 시 만난 미세 레이아웃 버그
체크리스트 구성을 위해 처음에는 flexbox 방식을 도입했습니다. 그러나 인쇄 출력 시 줄바꿈이 정상적으로 동작하지 않고 텍스트가 겹치거나 뒤틀리는 문제가 드러났습니다. 결국 flexbox 구조를 버리고 hanging indent(내어쓰기) 방식으로 전환하여 문맥에 맞는 자연스러운 정렬을 구현했습니다.
페이지 경계선 부근에 위치한 체크박스가 절반만 출력되고 잘려버리는 버그도 관찰되었습니다. 체크박스의 세로 정렬이 정밀하게 맞지 않는 현상까지 겹쳐서, 픽셀 단위로 정밀하게 위치 수치를 다시 재어가며 맞추는 세심한 작업이 필요했습니다.
문서 중간중간 등장하는 비교표 역시 페이지 경계에서 반토막이 나는 문제가 자주 일어났습니다. 표 중간에 어정쩡하게 절단되는 일을 막기 위해 비교표 요소에 page-break-inside: avoid 속성을 걸어 표 전체가 통째로 다음 페이지로 넘어가도록 처리했습니다.
이 모든 조판 작업은 수십 차례 스크린샷으로 피드백을 확인하고 코드를 수정하는 끈질긴 라운드 반복으로 진행되었습니다. 세밀한 CSS 스타일 조작과 반복 테스트를 통해 비로소 만족스러운 품질의 PDF 책을 얻어낼 수 있었습니다.