Markdown to PDF Converter Skill

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

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

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

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

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:

---

Security Compliance

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

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

---

Setup (One-Time)

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

Dependencies

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