md-to-pdf

name	md-to-pdf
version	1.0.0
category	data/documents
description	Convert Markdown documents with YAML frontmatter into styled, print-ready PDFs using Chrome headless.
type	reference
tags	[]

md-to-pdf Skill

Convert Markdown documents with YAML frontmatter into styled, print-ready PDFs using Chrome headless.

Quick Start

python3 .Codex/skills/data/documents/md-to-pdf/md_to_pdf.py document.md -o output.pdf

When to Use

• Professional reports (GTM strategy, proposals, engineering summaries)
• Any document that needs a styled cover page, section headers, and print-optimized layout
• When you need consistent PDF output without hand-coding HTML

Prerequisites

• Chrome: /usr/bin/google-chrome (v145+ recommended)
• Python: markdown library (v3.5.2+ with tables, fenced_code, toc, attr_list, meta, sane_lists)
• System Python 3.10+

CLI Reference

python3 md_to_pdf.py input.md [-o output.pdf] [--screenshot] [--no-cover] [--keep-html] [--template base]

Flag	Description
-o, --output	Output PDF path (default: <input>.pdf)
--screenshot	Also generate a QA PNG screenshot
--no-cover	Skip automatic cover page from frontmatter
--keep-html	Retain intermediate HTML file for inspection
--template	Template name from templates/ (default: base)

Frontmatter Reference

---
title: Document Title
subtitle: Subtitle displayed in accent color
date: February 16, 2026
author: Author Name
version: 1.0
confidentiality: Confidential
accent_color: "#0066cc"
footer: "Company Name | Confidential"
---

All fields are optional. title defaults to "Untitled Document".

Component Gallery

Section Header

<div class="section-header">
  <div class="section-label">SECTION 01</div>
  <h2>Executive Summary</h2>
</div>

Card

<div class="card">
  <h3>Item Name <span class="score-chip score-5">5/5</span></h3>
  <p><span class="field-label">Category:</span> Description text</p>
</div>

Tier Header

<div class="tier-header">Tier 1 — Critical Priority</div>

Score Chips

<span class="score-chip score-5">5/5</span>  <!-- teal -->
<span class="score-chip score-4">4/5</span>  <!-- blue -->
<span class="score-chip score-3">3/5</span>  <!-- orange -->
<span class="score-chip score-2">2/5</span>  <!-- red -->
<span class="score-chip score-1">1/5</span>  <!-- gray -->

Priority Badges

<span class="priority-badge high">High</span>
<span class="priority-badge medium">Medium</span>
<span class="priority-badge low">Low</span>
<span class="priority-badge ongoing">Ongoing</span>

Metric Grid

<div class="summary-grid">
  <div class="metric-card">
    <div class="metric-value">42</div>
    <div class="metric-label">Total Items</div>
  </div>
  <div class="metric-card">
    <div class="metric-value">$1.2M</div>
    <div class="metric-label">Revenue</div>
  </div>
</div>

Standard Markdown (auto-styled)

• Tables: dark header, zebra striping — use standard markdown table syntax
• Blockquotes: blue left-border callout — use > prefix
• Code blocks: dark background with monospace — use fenced code blocks
• Headings: h1 gets accent underline, h2-h4 styled progressively

Page Control

<div class="page-break"></div>       <!-- force page break -->
<div class="avoid-break">           <!-- keep content together -->
  ... content ...
</div>

Chrome Flags

The script uses these Chrome headless flags:

Flag	Purpose
--headless	No GUI window
--no-sandbox	Required in containers/CI
--disable-gpu	Prevents GPU errors in headless
--print-to-pdf=FILE	Generate PDF output
--no-pdf-header-footer	Suppress default Chrome header/footer
--print-background	Render CSS backgrounds (critical for gradients, chips)
--screenshot=FILE	Generate PNG for QA
--window-size=W,H	Viewport for screenshots

Integration with Engineering Reports

Existing HTML report generators (wall thickness, dynacard) can reuse components.css by including it as a stylesheet. The CSS components are independent of the markdown pipeline.

from pathlib import Path
css = (Path(__file__).parent / "../../.Codex/skills/data/documents/md-to-pdf/templates/components.css").read_text()

Browser QA Step

Always use --screenshot during development to visually verify layout before final PDF:

python3 md_to_pdf.py draft.md -o draft.pdf --screenshot --keep-html
# Check draft.png for visual issues
# Check draft.html for template injection correctness
# Final: draft.pdf

Troubleshooting

Issue	Cause	Fix
Blank PDF	Chrome not found	Verify which google-chrome
No background colors	Missing --print-background	Already set by default in script
Section headers cut off	Missing page-break-before	Use .section-header class (has it built-in)
Tables split across pages	Large table	Wrap in <div class="avoid-break">
Accent color wrong	Frontmatter typo	Check accent_color is valid CSS color with quotes
Cover page missing	--no-cover flag	Remove flag, or add frontmatter title