Mac-letterhead

A professional macOS utility that applies letterhead templates to PDF and Markdown documents. Mac-letterhead creates drag-and-drop applications that automatically merge your company letterhead with documents while preserving formatting and ensuring professional presentation.

What Mac-letterhead Does

Mac-letterhead transforms your letterhead PDF into a powerful document processing tool:

For PDF Documents

• Direct Overlay: Your letterhead is applied as an overlay to existing PDFs without reformatting the original document
• Multiple Blend Modes: Choose from various merging strategies (darken, multiply, overlay, transparency) to suit different letterhead designs
• Quality Preservation: All original formatting, fonts, and layout are maintained during the merge process

For Markdown Documents

• Intelligent Layout: Analyzes your letterhead PDF to identify headers, footers, logos, and text elements
• Smart Margin Detection: Automatically calculates the optimal printable area within your letterhead design
• Professional Rendering: Converts Markdown to beautifully formatted PDF with proper typography, tables, code blocks, and styling
• Adaptive Positioning: Handles left, right, and center-positioned letterheads with appropriate margin adjustments

Multi-Page Letterhead Support

• Single Page: Applied consistently to all document pages
• Two Pages: First page template for page 1, second template for subsequent pages
• Three Pages: Distinct templates for first page, even pages, and odd pages

Requirements

• macOS: Required for droplet applications and PDF processing
• Python: 3.10 or higher
• uv package manager: Install with pip install uv if needed

Installation

Install Mac-letterhead and create your first letterhead application:

# Quick start - create a letterhead droplet on your desktop
uvx mac-letterhead install --name "Company"

# For AI integration, install with MCP support
uvx install "mac-letterhead[mcp]"

Desktop Extension for Claude for macOS

The easiest way to use Mac-letterhead with Claude is via the Desktop Extension (.mcpb file). Download the latest mac-letterhead-<version>.mcpb from the GitHub Releases page and double-click it to install directly into Claude for macOS — no terminal required.

After installation, Claude's settings UI lets you configure:

• Letterhead Style: The style name to use (resolves ~/.letterhead/<style>.pdf and .css). Leave blank to specify a style per request.
• Output Directory: Where generated PDFs are saved (defaults to ~/Desktop).

For complete Desktop Extension details, see README_MCP.md.

MCP Registry

Mac-letterhead is published in the official MCP Registry, making it easily discoverable by AI assistants and MCP clients.

Find Mac-letterhead in:

• Official MCP Registry: https://registry.modelcontextprotocol.io
• GitHub MCP Registry: Automatically synced from official registry
• Community Directories: mcp.so and other MCP server catalogs

Quick Install for MCP Clients:

uvx mac-letterhead[mcp]

For complete MCP configuration and usage, see README_MCP.md.

Prerequisites

Mac-letterhead expects your letterhead files to be organized in ~/.letterhead/:

~/.letterhead/
├── company.pdf        # Your letterhead template
├── company.css        # Optional custom styling
└── personal.pdf       # Additional letterhead templates

This creates a macOS application that you can drag documents onto to apply your letterhead. The MCP option adds support for AI tool integration.

System Dependencies

For optimal Markdown rendering, install the required libraries:

brew install pango cairo fontconfig freetype harfbuzz

These libraries enable high-quality PDF generation with advanced typography support.

Usage

Creating Letterhead Applications

Basic Application Creation

# Create a letterhead droplet using ~/.letterhead/company.pdf
uvx mac-letterhead install --name "company"

Custom Letterhead Override

# Use a different letterhead file but keep the app name
uvx mac-letterhead install --name "Company Correspondence" --letterhead /path/to/custom-letterhead.pdf

Advanced Markdown Styling

# Create a letterhead application with custom CSS styling
uvx mac-letterhead install --name "Technical Reports" --css /path/to/custom-styles.css

The --css option allows you to customize the appearance of rendered Markdown documents:

• Typography: Custom fonts, sizes, colors, and spacing
• Layout: Table styling, code block formatting, list appearance
• Branding: Consistent styling that complements your letterhead design
• Responsiveness: Ensures content fits properly within the detected printable area

Install Command Reference

The install command follows this pattern:

uvx mac-letterhead install --name "AppName" [--letterhead path] [--css path] [--output-dir dir]

Required:

• --name: Sets both the application name and the style. Automatically looks for ~/.letterhead/<name>.pdf and ~/.letterhead/<name>.css

Optional:

• --letterhead: Override the default letterhead PDF path
• --css: Override the default CSS file path
• --output-dir: Specify where to create the app (default: Desktop)
• --dev: Create a development version using local code

Using Letterhead Applications

Once created, your letterhead application appears on your desktop:

1. For PDF Files: Drag any PDF onto the application icon - the letterhead is applied as an overlay
2. For Markdown Files: Drag .md files onto the application - they're converted to PDF with your letterhead and proper formatting
3. Preview Letterhead: Double-click the application to view information and preview the letterhead template

Direct Command-Line Usage

PDF Merging

# Apply letterhead to a PDF document
uvx mac-letterhead merge /path/to/letterhead.pdf "Document Title" ~/Desktop /path/to/document.pdf

# Use a specific blending strategy
uvx mac-letterhead merge /path/to/letterhead.pdf "Report" ~/Desktop /path/to/report.pdf --strategy overlay

Markdown Processing

# Convert Markdown with letterhead
uvx mac-letterhead merge-md /path/to/letterhead.pdf "Technical Guide" ~/Desktop /path/to/guide.md

# With custom CSS styling
uvx mac-letterhead merge-md /path/to/letterhead.pdf "Proposal" ~/Desktop /path/to/proposal.md --css /path/to/styles.css

AI Integration with MCP Server

Mac-letterhead includes an MCP (Model Context Protocol) server that enables AI tools like Claude to create letterheaded PDFs through natural language commands:

# Start a generic multi-style server
uvx mac-letterhead mcp

# Start a dedicated single-style server  
uvx mac-letterhead mcp --style easytocloud --output-dir ~/Documents/generated-pdfs

Usage Examples with Claude:

• "Using the letterhead server, create an easytocloud style PDF about our new cloud services"
• "Generate a personal letterheaded document for my consulting proposal"

The MCP server automatically:

• Converts Markdown content to professionally formatted PDFs
• Applies appropriate letterhead templates and CSS styling
• Manages output directories and file naming
• Supports both style-specific and generic multi-style configurations

For complete MCP setup and configuration details, see README_MCP.md.

Blending Strategies

Choose the optimal strategy for your letterhead design:

• darken (Default): Ideal for light letterheads with dark text/logos - provides excellent readability
• multiply: Creates watermark-like effects, good for subtle branding
• overlay: Balances visibility of both document content and letterhead elements
• transparency: Smooth blending with semi-transparent effects
• reverse: Places letterhead elements on top of document content

Advanced Features

Custom CSS Styling

Create sophisticated document styling by providing custom CSS:

/* custom-styles.css */
h1 { color: #2c5aa0; border-bottom: 2px solid #2c5aa0; }
table { border: 1px solid #ddd; background: #f9f9f9; }
code { background: #f4f4f4; padding: 2px 4px; }

The CSS is automatically integrated with Mac-letterhead's smart margin system to ensure content fits properly within your letterhead design.

Markdown Features

Mac-letterhead provides professional Markdown rendering with:

• Typography: Proper heading hierarchy, paragraph spacing, and font sizing
• Tables: Clean borders, consistent padding, and professional appearance
• Code Blocks: Syntax highlighting for multiple programming languages
• Lists & Quotes: Proper indentation and formatting for nested content
• Images & Links: Full support for embedded images and hyperlinks
• Math: LaTeX-style mathematical expressions (when supported)

GitHub Flavored Markdown Support

Mac-letterhead includes enhanced support for GitHub Flavored Markdown (GFM) features:

• Strikethrough: ~~deleted text~~ renders with proper strikethrough formatting
• Task Lists: Interactive-style checkboxes with - [x] completed and - [ ] pending
• Enhanced Tables: Improved table rendering with better alignment and styling
• Automatic Detection: GFM features are automatically enabled when the pycmarkgfm library is available

Task lists are rendered with professional Unicode checkboxes (☑ for completed, ☐ for pending) that are properly sized and aligned, including within table cells.

Dual Rendering Pipeline

Mac-letterhead features a sophisticated dual-backend rendering system that automatically selects the best available technology while providing manual control when needed.

PDF Rendering Backends

WeasyPrint (Preferred when available):

• Advantages: Superior CSS support, advanced typography, precise layout control
• Features: Full HTML5/CSS3 support, web fonts, complex layouts, print-specific CSS
• Requirements: System libraries (brew install pango cairo fontconfig freetype harfbuzz)
• Use Case: High-quality documents requiring advanced styling and typography

ReportLab (Reliable fallback):

• Advantages: Pure Python implementation, no system dependencies, consistent rendering
• Features: Professional PDF generation, basic HTML support, reliable cross-platform operation
• Requirements: None (included with Python installation)
• Use Case: Simple documents, environments without system library access

Markdown Processing Backends

GitHub Flavored Markdown (GFM) (Enhanced when available):

• Library: pycmarkgfm (Python bindings to GitHub's cmark-gfm parser)
• Features: Strikethrough, task lists, enhanced tables, autolinks, GitHub-compatible parsing
• Compatibility: Full compatibility with GitHub markdown rendering
• Use Case: Documents with GFM-specific features, GitHub repository documentation

Standard Markdown (Universal fallback):

• Library: Python markdown with extensions
• Features: CommonMark compliance, basic table support, code highlighting
• Compatibility: Works in all Python environments
• Use Case: Simple documents, maximum compatibility requirements

Backend Selection and Control

Automatic Selection (Default behavior):

# Uses best available backends automatically
uvx mac-letterhead merge-md letterhead.pdf "Document" ~/Desktop document.md

Manual Backend Control:

# Force specific PDF backend
uvx mac-letterhead merge-md letterhead.pdf "Report" ~/Desktop report.md --pdf-backend reportlab

# Force specific Markdown backend  
uvx mac-letterhead merge-md letterhead.pdf "Guide" ~/Desktop guide.md --markdown-backend standard

# Combine specific backends
uvx mac-letterhead merge-md letterhead.pdf "Technical" ~/Desktop tech.md --pdf-backend weasyprint --markdown-backend gfm

Available Backend Options:

• --pdf-backend: weasyprint, reportlab, auto (default: auto)
• --markdown-backend: gfm, standard, auto (default: auto)

Backend Capabilities Matrix

Feature	WeasyPrint + GFM	WeasyPrint + Standard	ReportLab + GFM	ReportLab + Standard
Basic Markdown	✅ Excellent	✅ Excellent	✅ Good	✅ Good
Advanced CSS	✅ Full Support	✅ Full Support	⚠️ Limited	⚠️ Limited
Strikethrough	✅ Native	❌ Not Available	✅ Unicode	❌ Not Available
Task Lists	✅ Styled Checkboxes	❌ Not Available	✅ Unicode Checkboxes	❌ Not Available
Complex Tables	✅ Advanced	✅ Good	✅ Basic	✅ Basic
Typography	✅ Professional	✅ Professional	✅ Standard	✅ Standard
System Dependencies	⚠️ Required	⚠️ Required	✅ None	✅ None

Testing and Validation

The project includes comprehensive testing for all backend combinations:

# Test all combinations across Python versions
make test-backend-combinations

# Test specific combinations
make test-weasyprint-gfm      # WeasyPrint + GitHub Flavored Markdown
make test-weasyprint-standard # WeasyPrint + Standard Markdown  
make test-reportlab-gfm       # ReportLab + GitHub Flavored Markdown
make test-reportlab-standard  # ReportLab + Standard Markdown

Each test combination generates output files with naming patterns like document-py3.11-weasyprint-gfm.pdf for easy comparison and quality validation.

Versioning & Publishing

Releases are automated with semantic-release via GitHub Actions. Use Conventional Commit messages on main and the workflow will:

• determine the next semantic version
• update letterhead_pdf/__init__.py, server.json, uv.lock, and CHANGELOG.md
• build the package and upload it to PyPI
• create the GitHub release and tag

Commit messages must follow the Conventional Commits format so semantic-release can infer the correct version bump.

Local tooling (optional)

1. Install once:

   npm install
   

2. Preview the next release without publishing:

   make release-dry-run
   

3. If you need to release from your workstation, provide your PyPI token and run:

   export TWINE_USERNAME=__token__
   export TWINE_PASSWORD=...
   make publish
   

The GitHub Action uses the same configuration, so merging Conventional Commits into main is usually all that’s required.

Use Cases

• Corporate Communications: Apply company branding to business correspondence
• Legal Documents: Add firm letterhead and disclaimers to contracts and legal papers
• Financial Documents: Brand invoices, statements, and financial reports
• Technical Documentation: Convert Markdown documentation to branded PDFs
• Academic Papers: Add institutional letterhead to research papers and reports
• Proposals & Reports: Create professional client deliverables from Markdown sources
• AI-Generated Content: Use Claude or other AI tools to create branded documents through natural language

Troubleshooting

Common Issues

Library Dependencies: If you see WeasyPrint warnings, the system automatically falls back to ReportLab - functionality is not affected.

File Permissions: If applications request file access, approve the permissions in System Preferences > Security & Privacy > Privacy > Files and Folders.

Margin Detection: The system automatically analyzes letterhead positioning. If margins appear incorrect, ensure your letterhead PDF contains clear visual elements (logos, text, graphics) in header/footer areas.

Log Files

• Application logs: ~/Library/Logs/Mac-letterhead/letterhead.log
• Droplet logs: ~/Library/Logs/Mac-letterhead/droplet.log

Contributing

We welcome contributions! Please see CONTRIBUTING.md for development setup, testing procedures, and pull request guidelines.

License

MIT License