---
name: md-to-pdf
description: Convert Markdown files to beautiful PDF documents. Use when user wants to convert .md to .pdf, create PDF from markdown, generate PDF documents, insert images or profile photos into PDFs/CVs, or needs Hebrew/RTL PDF support with proper text alignment.
allowed-tools: Read, Write, Bash, Glob
---
# Markdown to PDF Conversion Skill
Convert Markdown files to beautifully styled PDF documents with full support for:
- Hebrew text and RTL (right-to-left) layout
- Tables with proper styling
- Code blocks with syntax highlighting
- Headers, lists, and all Markdown elements
- Image and profile-photo placement
- Professional typography
## How It Works
This skill uses **Pandoc** + **WeasyPrint** for the best Hebrew/RTL support:
1. Pandoc converts Markdown to HTML
2. A custom CSS stylesheet applies beautiful styling
3. WeasyPrint renders the HTML to PDF with proper RTL support
## Installation (One-Time Setup)
If dependencies aren't installed, run:
```bash
# Install Pandoc
sudo apt-get update && sudo apt-get install -y pandoc
# Install WeasyPrint
pip install weasyprint
# Or with pipx (recommended)
pipx install weasyprint
```
## Usage
### Basic Conversion
To convert a markdown file to PDF:
```bash
~/.claude/skills/md-to-pdf/convert.sh input.md output.pdf
```
### With Custom Options
```bash
# Hebrew/RTL document
~/.claude/skills/md-to-pdf/convert.sh input.md output.pdf --rtl
# Include table of contents
~/.claude/skills/md-to-pdf/convert.sh input.md output.pdf --toc
# Both RTL and TOC
~/.claude/skills/md-to-pdf/convert.sh input.md output.pdf --rtl --toc
# Force LTR (English doc that quotes Hebrew/Arabic; inline RTL still renders right)
~/.claude/skills/md-to-pdf/convert.sh input.md output.pdf --ltr
```
### One-headline rule (always)
Every PDF gets exactly ONE top headline. If a file has both a YAML `title:` (which
pandoc renders as a title block) and a body `# H1`, the converter drops the title block
and keeps the body heading. So put the document title as a body `# H1`; a frontmatter
`title:` is optional and never produces a second headline. Never hand-author two `#`
top headings expecting both to show.
## Features
### Hebrew/RTL Support
- Automatic RTL text direction
- Right-aligned paragraphs
- Proper Hebrew font (David, Arial Hebrew, or system Hebrew font)
- Tables with RTL support
### Beautiful Styling
- Clean, professional typography
- Proper heading hierarchy
- Styled tables with alternating row colors
- Code blocks with syntax highlighting
- Blockquotes with left border
- Horizontal rules
## Image And Profile Photo Placement
When adding images to a PDF, especially a CV headshot or a first-page portrait, do not treat image placement as "just Markdown". It is visual layout work and must be checked in the rendered PDF.
### Profile Image Workflow
1. Inspect the source image before placing it.
- Check face/object centering, crop, aspect ratio, and empty margins.
- If the image needs a circular portrait, prepare the crop deliberately instead of relying on the original file.
2. Prefer raw HTML with stable classes over plain Markdown image syntax for important images.
3. Keep the header compact and balanced: photo, name/title/contact details, and no accidental large blank areas.
4. For critical circular portraits, render once and inspect the actual circle. If the mask, border, halo, or shadow is off, pre-compose the circular PNG and place that finished asset in the document.
5. After every photo adjustment, rebuild the PDF, render the page to an image, open it, and inspect the full page plus a zoom crop of the photo area.
Example header markup:
```html
```
If the circular crop was pre-composed as a final PNG with transparent background, use:
```html
```
### Image Path Rules
- Use relative paths from the Markdown file's working directory when possible.
- Use absolute paths only when the conversion command runs from a different directory and relative paths would be ambiguous.
- Confirm the image file exists before converting.
- Keep final image assets near the Markdown/PDF work folder, usually under `assets/`.
### Required Visual QA For PDFs
After conversion, always render and inspect the real PDF output:
```bash
~/.claude/skills/md-to-pdf/convert.sh input.md output.pdf --rtl
pdfinfo output.pdf
pdftoppm -png -r 180 output.pdf /tmp/output-page
```
Open every rendered page image before delivery. For portraits, logos, badges, and signatures, also inspect a zoomed crop of the affected area. If the rendered result is misaligned, cramped, off-center, blurry, awkwardly cropped, or visually weak, revise the source or asset and repeat the conversion and inspection loop.
Never claim a PDF was visually checked unless the rendered page image was actually opened.
### Tables
Tables are rendered with:
- Header row with background color
- Alternating row colors for readability
- Proper cell padding
- Border styling
### Code Blocks
- Monospace font
- Background highlighting
- Syntax highlighting support
- Proper line wrapping
## CSS Customization
The stylesheet is located at:
`~/.claude/skills/md-to-pdf/style.css`
Edit this file to customize:
- Colors and fonts
- Margins and spacing
- Table styling
- Code block appearance
## Troubleshooting
### Hebrew text not displaying
- Ensure a Hebrew-compatible font is installed (David, Arial Hebrew, Noto Sans Hebrew)
- The CSS includes fallback fonts
### Tables too wide
- Tables automatically shrink to fit page width
- Consider splitting very wide tables
### Images not showing
- Use relative paths or absolute URLs
- Ensure images exist at the specified paths
### Profile photo looks wrong after conversion
- Check the rendered PDF page, not only the Markdown preview.
- If CSS `border-radius`, masks, borders, or shadows render poorly, pre-compose the circular portrait as a finished PNG and place that asset.
- Re-render the PDF and inspect both the full page and a zoom crop of the image area before sending.
```
### Image Path Rules
- Use relative paths from the Markdown file's working directory when possible.
- Use absolute paths only when the conversion command runs from a different directory and relative paths would be ambiguous.
- Confirm the image file exists before converting.
- Keep final image assets near the Markdown/PDF work folder, usually under `assets/`.
### Required Visual QA For PDFs
After conversion, always render and inspect the real PDF output:
```bash
~/.claude/skills/md-to-pdf/convert.sh input.md output.pdf --rtl
pdfinfo output.pdf
pdftoppm -png -r 180 output.pdf /tmp/output-page
```
Open every rendered page image before delivery. For portraits, logos, badges, and signatures, also inspect a zoomed crop of the affected area. If the rendered result is misaligned, cramped, off-center, blurry, awkwardly cropped, or visually weak, revise the source or asset and repeat the conversion and inspection loop.
Never claim a PDF was visually checked unless the rendered page image was actually opened.
### Tables
Tables are rendered with:
- Header row with background color
- Alternating row colors for readability
- Proper cell padding
- Border styling
### Code Blocks
- Monospace font
- Background highlighting
- Syntax highlighting support
- Proper line wrapping
## CSS Customization
The stylesheet is located at:
`~/.claude/skills/md-to-pdf/style.css`
Edit this file to customize:
- Colors and fonts
- Margins and spacing
- Table styling
- Code block appearance
## Troubleshooting
### Hebrew text not displaying
- Ensure a Hebrew-compatible font is installed (David, Arial Hebrew, Noto Sans Hebrew)
- The CSS includes fallback fonts
### Tables too wide
- Tables automatically shrink to fit page width
- Consider splitting very wide tables
### Images not showing
- Use relative paths or absolute URLs
- Ensure images exist at the specified paths
### Profile photo looks wrong after conversion
- Check the rendered PDF page, not only the Markdown preview.
- If CSS `border-radius`, masks, borders, or shadows render poorly, pre-compose the circular portrait as a finished PNG and place that asset.
- Re-render the PDF and inspect both the full page and a zoom crop of the image area before sending.