Markdown to PDF Converter Skill

Purpose

Convert Markdown files to professional PDF documents using WeasyPrint (HTML→PDF engine) with customizable CSS styling. Runs entirely in sandbox with no external dependencies beyond Python packages.

Architecture

Technology Stack

markdown

weasyprint

Why This Stack?

• Pure Python: No subprocess calls, no external tools (Pandoc, LaTeX) required
• Sandbox-Safe: Works within Cursor sandbox restrictions
• CSS Control: Full styling customization via CSS
• Quality Output: Professional typography with proper page handling

Features

Markdown Support

[TOC]

PDF Features

• Page sizes: A4, Letter, Legal, custom dimensions
• Margins: Configurable (default: 2.5cm)
• Headers/Footers: Page numbers, document title, date
• Page breaks: Before major sections (configurable)
• Typography: Professional fonts, proper line-height

Workflow

Step 1: Understand Request

• What Markdown file(s) need conversion?
• Any specific styling requirements?
• Output filename/location preference?
• Page size requirements (A4 default)?

Step 2: Check/Setup Environment

# One-time setup (if not done)
cd /Users/samarvir/code/autodesk/Product\ management
source .venv/bin/activate
pip install markdown weasyprint

Step 3: Execute Conversion

# Basic conversion
python .claude/skills/md-to-pdf/convert_md_to_pdf.py input.md output.pdf

# With options
python .claude/skills/md-to-pdf/convert_md_to_pdf.py input.md output.pdf \
  --css custom.css \
  --page-size letter \
  --title "Document Title"

Step 4: Report Results

**PDF Generated Successfully**

**Input**: input.md
**Output**: Output/document.pdf
**Pages**: [N] pages
**Size**: [X] KB

Styling: [default/custom CSS path]

Usage Options

Command Line Arguments

input

output

--css

--page-size

a4

--margin

2.5cm

--title

--no-toc

--no-header

--no-footer

Examples

Basic Conversion

python .claude/skills/md-to-pdf/convert_md_to_pdf.py \
  Initiatives/docs-integration/prd.md \
  Output/prd.pdf

With Custom Styling

python .claude/skills/md-to-pdf/convert_md_to_pdf.py \
  Initiatives/ai-renderings/case-for-a-new-squad.md \
  Operations/adhoc/ai-renderings/proposal.pdf \
  --css .claude/skills/md-to-pdf/styles/autodesk.css \
  --title "AI Renderings Squad Proposal"

Letter Size for US Audience

python .claude/skills/md-to-pdf/convert_md_to_pdf.py \
  document.md \
  document.pdf \
  --page-size letter \
  --margin 1in

CSS Themes

Available Themes

default.css

autodesk.css

minimal.css

Custom CSS

Create your own CSS file with:

• @page

  rules for margins, headers, footers
• Typography settings (fonts, sizes, line-height)
• Table styling
• Code block formatting
• Color schemes

Example custom CSS sections:

/* Page setup */
@page {
  size: A4;
  margin: 2.5cm;
  @top-center { content: "Document Title"; }
  @bottom-right { content: "Page " counter(page); }
}

/* Typography */
body {
  font-family: 'Helvetica Neue', Arial, sans-serif;
  font-size: 11pt;
  line-height: 1.6;
}

/* Headers */
h1 { color: #1D91D0; page-break-before: always; }
h1:first-of-type { page-break-before: avoid; }

Output Location Guidelines

Follow the project's Output Location Protocol:

Initiatives/[name]/

Initiatives/ai-renderings/prd.pdf

Operations/recurring/

leadership-reviews/q1-2026.pdf

Operations/adhoc/[topic]/

adhoc/market-analysis/report.pdf

Output/

Output/test.pdf

Security Compliance

eval

exec

Input Sanitization

• HTML content is escaped by default
• Raw HTML in Markdown disabled unless explicitly enabled
• Image paths validated (local only, no URLs without flag)
• File size warnings for documents > 1MB source

Troubleshooting

Common Issues

--base-path

table { width: 100%; }

h1 { page-break-before: always; }

Debug Mode

python .claude/skills/md-to-pdf/convert_md_to_pdf.py input.md output.pdf --debug

Outputs:

• Intermediate HTML (for inspection)
• CSS applied
• Any warnings/errors

File Locations

.claude/skills/md-to-pdf/SKILL.md

.claude/skills/md-to-pdf/convert_md_to_pdf.py

.claude/skills/md-to-pdf/default.css

.claude/skills/md-to-pdf/styles/

Setup (One-Time)

cd /Users/samarvir/code/autodesk/Product\ management
source .venv/bin/activate
pip install markdown weasyprint

Dependencies

markdown

weasyprint

System Requirements

WeasyPrint requires some system libraries. On macOS:

brew install pango

If you encounter font issues:

brew install fontconfig

API Usage (Programmatic)

For integration with other scripts:

from convert_md_to_pdf import MarkdownToPDF

converter = MarkdownToPDF(
    css_path="default.css",
    page_size="a4",
    margin="2.5cm"
)

# Convert file
converter.convert_file("input.md", "output.pdf")

# Convert string
converter.convert_string(
    markdown_text="# Hello World\n\nThis is a test.",
    output_path="output.pdf",
    title="Test Document"
)

Best Practices

DO

• ✅ Use semantic Markdown (proper header hierarchy)
• ✅ Keep images local or use absolute URLs
• ✅ Test with

  --debug

  first for complex documents
• ✅ Use CSS for all styling (not inline HTML)
• ✅ Add

  [TOC]

  for documents > 5 pages

DON'T

• ❌ Embed raw HTML unless necessary
• ❌ Use complex nested tables
• ❌ Expect pixel-perfect browser rendering
• ❌ Use remote images without

  --allow-remote

  flag

Response Templates

Conversion Acknowledgment

I'll convert the Markdown file to PDF.

**Input**: [filename.md]
**Output**: [path/output.pdf]
**Styling**: [default/custom]
**Page Size**: [A4/Letter]

Converting...

Conversion Complete

**PDF Generated Successfully**

**File**: `Output/[filename].pdf`
**Pages**: [N] pages
**Size**: [X] KB

The PDF includes:
- [TOC if present]
- [N] sections
- [N] tables
- [N] images

Open the PDF to review formatting.

Conversion Failed

**PDF Generation Failed**

**Error**: [error message]

Troubleshooting:
1. [specific fix based on error]
2. Run with `--debug` for more info
3. Check CSS syntax if using custom styles