path
Jin's Lab
코드로 실험하고 기록하는 개발 일지 · J.Lab

Jin's Lab

코드로 실험하고 기록하는 개발 일지. 커리어와 삶의 방향을 탐색하며 기록하는 공간입니다

css-print

마크다운 PDF 변환 파이프라인과 CSS 인쇄 조판 삽질기

J.Lab ·
목차

    원고 작성을 마크다운으로 완료한 후, 이를 보기 좋은 PDF 책으로 출판하기 위한 작업에 착수했습니다. 파이프라인 자체는 Python의 markdown 라이브러리와 pymdown-extensions 확장 패키지를 활용해 HTML을 먼저 생성한 다음, Playwright(Chromium)를 구동하여 PDF로 뽑아내는 방식으로 구축했습니다. 툴을 만드는 것까지는 일사천리로 진행되었지만, 진짜 난관은 바로 출력물 형태를 다듬는 인쇄 조판 작업이었습니다.

    단순히 마크다운 PDF 변환 처리를 실행하는 것에 그치지 않고, 책 형태의 다듬어진 완성도를 얻기 위해서는 디테일한 CSS 인쇄 스타일 적용이 필수적이었습니다. 이 과정에서 발생한 수많은 레이아웃 깨짐 현상과 싸우며 고군분투한 경험을 정리해보았습니다.

    마크다운 문서를 PDF 책으로 변환하는 자동화 파이프라인 일러스트

    마크다운에서 Playwright PDF로 이어지는 변환 파이프라인

    기본적인 변환 흐름은 간단했습니다. 텍스트 원고에 포함된 체크리스트와 각종 특수 구문을 지원하기 위해 Python markdown 라이브러리에 pymdown-extensions 확장 모듈을 붙여 HTML 파일로 변환했습니다. 그 후 Headless 브라우저를 컨트롤하는 Playwright PDF 변환 기능을 호출해 웹 화면을 그대로 인쇄하듯 결과물을 생성했습니다.

    하지만 브라우저 화면에서 깔끔하게 보이던 화면이 PDF로 인쇄 조판을 거치자 수많은 레이아웃 왜곡을 일으키기 시작했습니다. 화면상에서는 전혀 문제가 없던 요소들이 페이지 경계선에 걸치면서 심각한 조판 버그를 드러냈습니다.

    CSS 인쇄 스타일 조판 오류와 레이아웃 수정을 표현한 기술 일러스트

    페이지 넘김 시 배경이 깨지는 box-decoration-break 해결

    가장 먼저 직면한 큰 문제는 페이지가 넘어갈 때 박스 요소의 좌우 배경색이 날아가고 뜬금없는 흰 여백이 노출되는 현상이었습니다. 문서가 여러 페이지에 걸쳐 인쇄되면서 첫 페이지 이후의 요소에서 스타일 연쇄가 끊기는 것이 원인이었습니다.

    이 문제는 CSS 속성인 box-decoration-break: clone을 선언해주면서 깨끗하게 해결되었습니다. 속성을 적용하자 모든 페이지 경계마다 박스의 배경색과 패딩이 동일하게 반복 복사되어 들어가면서 매끄러운 디자인을 유지할 수 있었습니다.

    또한 원고의 흐름상 특정 소제목이 항상 새로운 페이지 상단에서 시작되도록 강제할 필요가 있었습니다. 이를 위해 원하는 소제목 위치 앞에 직접 작성한 커스텀 마커를 배치하고, 페이지 전환 규칙을 적용해 원하는 위치에서 깔끔하게 단락이 넘어가도록 설정했습니다.

    체크리스트와 표 레이아웃 세부 정렬 조판 작업을 보여주는 일러스트

    체크리스트와 비교표 조판 시 만난 미세 레이아웃 버그

    체크리스트 구성을 위해 처음에는 flexbox 방식을 도입했습니다. 그러나 인쇄 출력 시 줄바꿈이 정상적으로 동작하지 않고 텍스트가 겹치거나 뒤틀리는 문제가 드러났습니다. 결국 flexbox 구조를 버리고 hanging indent(내어쓰기) 방식으로 전환하여 문맥에 맞는 자연스러운 정렬을 구현했습니다.

    페이지 경계선 부근에 위치한 체크박스가 절반만 출력되고 잘려버리는 버그도 관찰되었습니다. 체크박스의 세로 정렬이 정밀하게 맞지 않는 현상까지 겹쳐서, 픽셀 단위로 정밀하게 위치 수치를 다시 재어가며 맞추는 세심한 작업이 필요했습니다.

    문서 중간중간 등장하는 비교표 역시 페이지 경계에서 반토막이 나는 문제가 자주 일어났습니다. 표 중간에 어정쩡하게 절단되는 일을 막기 위해 비교표 요소에 page-break-inside: avoid 속성을 걸어 표 전체가 통째로 다음 페이지로 넘어가도록 처리했습니다.

    이 모든 조판 작업은 수십 차례 스크린샷으로 피드백을 확인하고 코드를 수정하는 끈질긴 라운드 반복으로 진행되었습니다. 세밀한 CSS 스타일 조작과 반복 테스트를 통해 비로소 만족스러운 품질의 PDF 책을 얻어낼 수 있었습니다.

    함께 읽으면 좋은 글

    • AI 전자책 집필 단정적인 문장과 과장된 약속 검수하기
    • 전자책 판매 플랫폼 사업자 없이 빠르게 시작하는 법
    • AI 부업 수익화 고민 클로드와 10개 후보 거르고 1위 찾은 솔직 후기
    css-print markdown pdf-generation playwright python-markdown typesetting
    ← 이전 글
    최근 게시물
    다음 글 →
    이전 게시물
    ≡ 글 목록으로
    소개
    path
    J.Lab

    커리어와 삶의 방향을 탐색하며
    기록하는 공간입니다

    카테고리
    403 Forbidden Error 1 429 Error 1 Ad Exchange 1 Ad Layout Guide 1 ad-slot 1 adsense 2 AdSense 2 AdSense Bot Detection 1 AdSense CTR 1 AdSense Display Issue 1 adsense-optimization 1 AI Automation 1 AI Image Generation 1 ai-automation 2 ai-book-writing 1 ai-image-generation 1 AI-Prompting 1 ai-side-hustle 1 ai-workflow 1 ai-writing 1 AIAutomation 1 AIBlogAutomation 1 AICodeLog 1 AIContentGeneration 1 AIImageGeneration 1 AIWritingErrors 1 API Automation 2 API Retry Design 1 api-automation 1 API-Deprecation 1 api-error 1 api-fallback 1 api-integration 2 api-pagination 1 api-retry-strategy 1 api-troubleshooting 1 APIDebugging 1 APIError 1 APIErrorHandling 1 APIIntegration 3 APIQuotaOptimization 1 APITokenRenewal 1 apps-script-trigger 1 AppsScript 1 appsScriptAutomation 1 AutomatedBlogging 1 automation 5 Automation 4 Automation Queue 1 Automation Scheduler 1 Automation Troubleshooting 1 automation-error 1 automation-script 1 AutomationBug 1 AutomationTroubleshooting 1 Backoff Algorithm 1 Base64 Image 1 Base64Encoding 1 batch-processing 1 BatchProcessing 1 Blog Optimization 2 blog-automation 4 blog-customization 2 blog-migration 4 blog-monetization 1 Blog-Sorting 1 blog-strategy 1 blog-theme-customization 1 blog-workflow 1 blogautomation 1 BlogAutomation 4 Blogger 13 Blogger API 2 Blogger Automation 2 Blogger SEO 1 blogger-api 4 blogger-automation 1 blogger-customization 1 blogger-error-400 1 blogger-labels 1 blogger-seo 1 blogger-theme 1 blogger-theme-debug 1 blogger-tips 1 Blogger-Tips 1 blogger-xml 1 BloggerAPI 7 BloggerAutomation 1 BloggerBypath 1 BloggerCustomization 2 BloggerFavicon 1 BloggerPermalink 1 BloggerTemplate 1 BloggerTemplateEditing 1 BloggerTheme 3 BloggerThemeCustomization 1 BloggerXMLStructure 1 Blogging-Automation 1 BloggingTools 1 BlogQuality 1 BlogSpot 1 Bug Fix 1 bug-fix 1 bug-hunting 1 BWidgetBIncludable 1 card-overlay-css 1 CardClickHandler 1 career-advice 1 CDATA 1 checklist-template 1 clamping-text 1 Claude 1 claude-ai 3 claude-code 2 ClaudeChat 1 ClaudeCode 1 CLIPTokenLimit 1 CloudflareWorkersAI 1 CNAME 1 Code Cleanup 1 Code Integration 1 code-refactoring 1 codelog 1 CodeLog 1 codeRefactoring 1 CodeStack 1 coding-log 2 comment-classification 1 config-pattern 1 Content Strategy 1 Content-Marketing 1 content-monetization 1 content-strategy 1 content-writing 1 contentsequencing 1 ContentStrategy 1 context-management 1 cost-reduction 1 CSS 1 css-axis-rotation 1 css-bug-fix 1 CSS-Debugging 1 css-fix 1 css-flexbox 1 css-layout 3 css-logo 1 css-print 1 css-troubleshooting 1 CSSLayout 1 CSSOverlay 1 Custom Domain 1 custom-theme 1 data-backfill 1 data-parsing 1 data-synchronization 1 data-validation 1 DatabaseDesign 1 DataMigration 1 DataRecovery 1 DataValidation 1 DateInjection 1 debugging 2 Debugging 5 Debugging Log 1 DebuggingLog 1 derived-state 1 detail-page-design 1 dev-journey 2 dev-log 1 Developer-Blog 1 developer-career 1 DeveloperJourney 2 DevJourney 1 DevLog 1 digital-creator 1 digital-products 2 display-none-seo 1 DOM-Inspection 1 dom-manipulation 1 Domain Migration 1 DomainMigration 1 DOMAutomation 1 duplicate-content 1 dynamic-menu 1 ebook-marketing 2 ebook-planning 1 ebook-publishing 5 editing-tips 1 Error Handling 2 error-handling 1 Error-Handling 1 ErrorHandling 2 EventDispatch 1 Execution Timeout 1 ExecutionLimit 1 exponential-backoff 1 FactChecking 1 FallbackSystem 1 FaviconEmbedding 1 Feed-API 1 filesystem 1 Flat Illustration 1 flux-model 1 FluxModel 1 FreeAIImage 1 frontend 1 Frontend 1 frontend-developer 1 frontend-layout 1 frontend-tips 1 FrontEndDev 1 FrontendTips 1 GAS 1 GAS Blogger API 1 GAS Refactoring 1 GAS Trigger 1 gas-automation 2 gas-optimization 1 gas-trigger 1 GASTimeout 1 gasTriggerManagement 1 GCP Project Linkage 1 Gemini 1 Gemini API 2 gemini-api 1 GeminiAPI 3 GeminiPrompt 1 GeminiPromptEngineering 1 getBoundingClientRect 1 github-raw-url 1 GmailRestrictions 1 Google AdSense 1 Google Apps Script 12 Google Discover 1 google-apps-script 8 Google-Apps-Script 1 google-blogger 1 googleAppsScript 1 GoogleAppsScript 12 googlesapps-script 1 GoogleSearchConsole 1 grep 1 hero-image 1 hero-image-validation 1 HTML Fix 1 HTMLCSS 1 HTMLWidgetBlogger 1 http-429 1 HuggingFace 1 HuggingFaceAPI 1 ico-generator 1 Image Optimization 1 image-automation 2 image-generation 1 image-hosting 1 image-optimization 1 image-processing 1 image-upload 1 ImageGeneration 2 ImageIntegrity 1 ImageOptimization 1 In-App Browser 1 invalid-argument 1 javascript 4 JavaScript 4 javascript-automation 1 javascript-toc 1 JavaScriptDevLog 1 JavaScriptInjection 1 jlab-codelog 1 JLabDevLog 1 json-schema 1 label-length-limit 1 lead-magnet 1 legacy-code 1 LinkedIn-API 2 LinkedIn-OAuth 1 LinkHub 1 linux 1 markdown 1 meta-description 1 MetaTags 1 Migration 1 Migration Script 1 mobile-friendly 1 Mobile-Web 1 monetization 1 Monitoring Automation 1 MultilingualSEO 1 NakedDomain 1 Negative Prompt 1 node-js 1 nodejs-automation 1 noindex-tag 1 Notion API 1 notion-api 3 notion-database 2 notion-gas-integration 1 notion-setup 1 notion-template 1 NotionAPI 3 NotionAutomation 1 notionintegration 1 NotionIntegration 1 OAuth Scope 1 OpenGraph 1 padding-overlap 1 pagination 1 payload-validation 1 pdf-generation 1 pdf-publishing 1 pdf-selling 1 permalink-management 1 PersonaDesign 1 pil-image-processing 1 Pinterest 2 PinterestAutomation 1 PipelineFix 1 playwright 1 Pollinations 1 Pollinations Flux 1 pollinations-ai 1 pollinations-api 2 PollinationsAI 1 PositionAbsolute 1 post-queue 1 productivity-tools 1 Prompt Design 1 Prompt Engineering 1 prompt-engineering 3 Prompt-Engineering 1 prompt-validation 1 PromptEngineering 3 Publishing Flow 1 publishorder 1 python-favicon 1 python-markdown 1 python-pil 2 python-scripting 1 Queue Design 1 queue-pattern 1 queue-stuck 1 RandomDelay 1 rate-limiting 1 react 1 React 1 Refactoring 1 Resource Exhausted 1 responsive-ads 1 responsive-design 4 ResponsiveCSS 1 ResponsiveDesign 1 retrospective 1 rfc3339 2 Robots Meta Tag 1 RSS Feed 1 rss-feed 1 RSSProxy 2 SAXParseException 1 Script Authorization 1 scriptNotFound 1 SDXL 1 Search Engine Optimization 2 Search-Engine-Optimization 1 SearchConsole 1 Self Rescheduling Trigger 1 SEO 2 SEO Tips 1 seo-optimization 5 SEO-Optimization 1 SEOOptimization 2 seriesmanagement 1 serverless-automation 1 sessionstart-hook 1 shell-script 1 Side Ad Duplication 1 side-income 1 side-project 1 SidebarLinks 1 SNSMarketing 1 Social-Media-Automation 2 SocialSharing 1 state-management 1 StaticWebPage 1 sub-agent 1 SVG Icon 1 svg-mask 1 SVGIcon 1 Synchronization 1 table-of-contents 1 tech-blogging 1 TechJournal 1 TechVibe 1 Template 1 TextSanitization 1 threads-api 2 Threads-API-Comparison 1 ThreadsAPI 3 time-driven-trigger 1 Tistory 2 tistory-customization 1 tistory-migration 1 tistory-skin 1 tistory-theming 1 tistory-tips 1 TOC Ad Placement 1 token-optimization 1 TranslationAPI 1 transparent-favicon 1 triggerCleanup 1 troubleshooting 2 Troubleshooting 2 typesetting 1 ui-optimization 1 unzip 1 URL Slug 1 UrlFetchApp 1 usememo 1 UTF8Encoding 1 vanilla-js 1 Web Development 2 Web Publishing 2 Web Security 1 web-development 7 Web-Development 2 web-development-log 1 web-development-tips 1 web-layout 1 Web-Layout 1 web-performance 1 web-publisher 1 web-scraping 1 WebAccessibility 1 WebAutomation 1 WebDebugging 1 WebDesign 2 WebDevelopment 10 WebDevelopmentTips 1 WebDevJourney 1 WebMigration 1 windows 1 windows-task-scheduler 2 WorkAutomation 1 workflow-automation 1 WorkflowAutomation 1 writing-process 1 XHTML 1 XMLCustomization 1 XMLParser 1 XMLSpecialCharacters 1 XMLTheme 1 z-index-issue 1 zip 1
    인기 글
    GAS에서 Blogger API 403 오류 완전 정복 — appsscript.json 스코프와 GCP 프로젝트 연결
    GAS에서 Blogger API 403 오류 완전 정복 — appsscript.json 스코프와 GCP 프로젝트 연결
    GAS 트리거 방치했다가 오류 폭탄 맞은 이야기 — 함수명 바꿀 때 트리거도 꼭 같이 정리하세요
    GAS 트리거 방치했다가 오류 폭탄 맞은 이야기 — 함수명 바꿀 때 트리거도 꼭 같이 정리하세요
    Notion API page_size 함정 — 우선순위 항목이 조회에서 빠지는 이유와 해결법
    Notion API page_size 함정 — 우선순위 항목이 조회에서 빠지는 이유와 해결법
    다른 블로그
    IssueLog
    IssueLog
    issuelog.jinbytes.com
    KidStory
    KidStory
    kidstory.jinbytes.com
    IT Story
    IT Story
    jinbytes.com
    이야기하는 밤
    이야기하는 밤
    story.jinbytes.com
    [eBook] 개발자로 살아간다는 것
    [eBook] 개발자로 살아간다는 것
    유료 전자책
    [eBook] FE 실무 디테일
    [eBook] FE 실무 디테일
    유료 전자책
    [미니북] FE 실무 디테일
    [미니북] FE 실무 디테일
    무료 미니북
    © Jin's Lab · J.Lab · All Rights Reserved
    jinbytes.com · Powered by Blogger