{"id":46152905,"url":"https://github.com/easytocloud/mac-letterhead","last_synced_at":"2026-04-03T09:01:23.297Z","repository":{"id":283084419,"uuid":"950587566","full_name":"easytocloud/Mac-letterhead","owner":"easytocloud","description":"A macOS utility and MCP-server for merging your letterhead with PDF and Markdown documents","archived":false,"fork":false,"pushed_at":"2026-03-24T17:38:17.000Z","size":5480,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-25T08:54:38.685Z","etag":null,"topics":["document-processing","drag-and-drop","letterhead","macos","markdown","mcp-server","pdf","pdf-tools","stationery","watermark"],"latest_commit_sha":null,"homepage":"https://easytocloud.github.io/mac-letterhead/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/easytocloud.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-18T11:46:42.000Z","updated_at":"2026-03-24T17:38:21.000Z","dependencies_parsed_at":"2025-07-09T09:23:09.368Z","dependency_job_id":"ce18106b-8d95-44a8-845d-e8b224d0d2ca","html_url":"https://github.com/easytocloud/Mac-letterhead","commit_stats":null,"previous_names":["easytocloud/mac-letterhead"],"tags_count":114,"template":false,"template_full_name":null,"purl":"pkg:github/easytocloud/Mac-letterhead","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/easytocloud%2FMac-letterhead","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/easytocloud%2FMac-letterhead/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/easytocloud%2FMac-letterhead/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/easytocloud%2FMac-letterhead/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/easytocloud","download_url":"https://codeload.github.com/easytocloud/Mac-letterhead/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/easytocloud%2FMac-letterhead/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31344430,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T08:03:20.796Z","status":"ssl_error","status_checked_at":"2026-04-03T08:00:37.834Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["document-processing","drag-and-drop","letterhead","macos","markdown","mcp-server","pdf","pdf-tools","stationery","watermark"],"created_at":"2026-03-02T09:08:39.430Z","updated_at":"2026-04-03T09:01:23.284Z","avatar_url":"https://github.com/easytocloud.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mac-letterhead\n\n\u003c!-- mcp-name: io.github.easytocloud/mac-letterhead --\u003e\n\n![PyPI Version](https://img.shields.io/pypi/v/Mac-letterhead.svg)\n![Build Status](https://github.com/easytocloud/Mac-letterhead/actions/workflows/publish.yml/badge.svg)\n![License](https://img.shields.io/github/license/easytocloud/Mac-letterhead.svg)\n![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue?logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTEyIDJMMyA3TDEyIDEyTDIxIDdMMTIgMloiIGZpbGw9IndoaXRlIi8+CjxwYXRoIGQ9Ik0zIDdWMTdMMTIgMjJWMTJMMyA3WiIgZmlsbD0id2hpdGUiLz4KPHBhdGggZD0iTTIxIDdWMTdMMTIgMjJWMTJMMjEgN1oiIGZpbGw9IndoaXRlIi8+Cjwvc3ZnPgo=)\n\n\u003c!-- GitHub can't render .icns files directly, so we use HTML to link the icon badge --\u003e\n\u003ca href=\"https://pypi.org/project/Mac-letterhead/\" title=\"Mac-letterhead on PyPI\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/easytocloud/Mac-letterhead/main/letterhead_pdf/resources/icon.png\" width=\"128\" height=\"128\" alt=\"Mac-letterhead Logo\" align=\"right\" /\u003e\n\u003c/a\u003e\n\nA 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.\n\n## What Mac-letterhead Does\n\nMac-letterhead transforms your letterhead PDF into a powerful document processing tool:\n\n### For PDF Documents\n- **Direct Overlay**: Your letterhead is applied as an overlay to existing PDFs without reformatting the original document\n- **Multiple Blend Modes**: Choose from various merging strategies (darken, multiply, overlay, transparency) to suit different letterhead designs\n- **Quality Preservation**: All original formatting, fonts, and layout are maintained during the merge process\n\n### For Markdown Documents  \n- **Intelligent Layout**: Analyzes your letterhead PDF to identify headers, footers, logos, and text elements\n- **Smart Margin Detection**: Automatically calculates the optimal printable area within your letterhead design\n- **Professional Rendering**: Converts Markdown to beautifully formatted PDF with proper typography, tables, code blocks, and styling\n- **Adaptive Positioning**: Handles left, right, and center-positioned letterheads with appropriate margin adjustments\n\n### Multi-Page Letterhead Support\n- **Single Page**: Applied consistently to all document pages\n- **Two Pages**: First page template for page 1, second template for subsequent pages  \n- **Three Pages**: Distinct templates for first page, even pages, and odd pages\n\n## Requirements\n\n- **macOS**: Required for droplet applications and PDF processing\n- **Python**: 3.10 or higher\n- **uv package manager**: Install with `pip install uv` if needed\n\n## Installation\n\nInstall Mac-letterhead and create your first letterhead application:\n\n```bash\n# Quick start - create a letterhead droplet on your desktop\nuvx mac-letterhead install --name \"Company\"\n\n# For AI integration, install with MCP support\nuvx install \"mac-letterhead[mcp]\"\n```\n\n### Desktop Extension for Claude for macOS\n\nThe easiest way to use Mac-letterhead with Claude is via the Desktop Extension (`.mcpb` file). Download the latest `mac-letterhead-\u003cversion\u003e.mcpb` from the [GitHub Releases page](https://github.com/easytocloud/Mac-letterhead/releases) and double-click it to install directly into Claude for macOS — no terminal required.\n\nAfter installation, Claude's settings UI lets you configure:\n- **Letterhead Style**: The style name to use (resolves `~/.letterhead/\u003cstyle\u003e.pdf` and `.css`). Leave blank to specify a style per request.\n- **Output Directory**: Where generated PDFs are saved (defaults to `~/Desktop`).\n\nFor complete Desktop Extension details, see [README_MCP.md](README_MCP.md).\n\n### MCP Registry\n\nMac-letterhead is published in the [official MCP Registry](https://registry.modelcontextprotocol.io/servers/io.github.easytocloud/mac-letterhead), making it easily discoverable by AI assistants and MCP clients.\n\n**Find Mac-letterhead in**:\n- **Official MCP Registry**: https://registry.modelcontextprotocol.io\n- **GitHub MCP Registry**: Automatically synced from official registry\n- **Community Directories**: mcp.so and other MCP server catalogs\n\n**Quick Install for MCP Clients**:\n```bash\nuvx mac-letterhead[mcp]\n```\n\nFor complete MCP configuration and usage, see [README_MCP.md](README_MCP.md).\n\n### Prerequisites\n\nMac-letterhead expects your letterhead files to be organized in `~/.letterhead/`:\n\n```bash\n~/.letterhead/\n├── company.pdf        # Your letterhead template\n├── company.css        # Optional custom styling\n└── personal.pdf       # Additional letterhead templates\n```\n\nThis creates a macOS application that you can drag documents onto to apply your letterhead. The MCP option adds support for AI tool integration.\n\n### System Dependencies\n\nFor optimal Markdown rendering, install the required libraries:\n\n```bash\nbrew install pango cairo fontconfig freetype harfbuzz\n```\n\nThese libraries enable high-quality PDF generation with advanced typography support.\n\n## Usage\n\n### Creating Letterhead Applications\n\n#### Basic Application Creation\n```bash\n# Create a letterhead droplet using ~/.letterhead/company.pdf\nuvx mac-letterhead install --name \"company\"\n```\n\n#### Custom Letterhead Override\n```bash\n# Use a different letterhead file but keep the app name\nuvx mac-letterhead install --name \"Company Correspondence\" --letterhead /path/to/custom-letterhead.pdf\n```\n\n#### Advanced Markdown Styling\n```bash\n# Create a letterhead application with custom CSS styling\nuvx mac-letterhead install --name \"Technical Reports\" --css /path/to/custom-styles.css\n```\n\nThe `--css` option allows you to customize the appearance of rendered Markdown documents:\n- **Typography**: Custom fonts, sizes, colors, and spacing\n- **Layout**: Table styling, code block formatting, list appearance\n- **Branding**: Consistent styling that complements your letterhead design\n- **Responsiveness**: Ensures content fits properly within the detected printable area\n\n#### Install Command Reference\n\nThe install command follows this pattern:\n\n```bash\nuvx mac-letterhead install --name \"AppName\" [--letterhead path] [--css path] [--output-dir dir]\n```\n\n**Required:**\n- `--name`: Sets both the application name and the style. Automatically looks for `~/.letterhead/\u003cname\u003e.pdf` and `~/.letterhead/\u003cname\u003e.css`\n\n**Optional:**\n- `--letterhead`: Override the default letterhead PDF path  \n- `--css`: Override the default CSS file path\n- `--output-dir`: Specify where to create the app (default: Desktop)\n- `--dev`: Create a development version using local code\n\n### Using Letterhead Applications\n\nOnce created, your letterhead application appears on your desktop:\n\n1. **For PDF Files**: Drag any PDF onto the application icon - the letterhead is applied as an overlay\n2. **For Markdown Files**: Drag .md files onto the application - they're converted to PDF with your letterhead and proper formatting\n3. **Preview Letterhead**: Double-click the application to view information and preview the letterhead template\n\n### Direct Command-Line Usage\n\n#### PDF Merging\n```bash\n# Apply letterhead to a PDF document\nuvx mac-letterhead merge /path/to/letterhead.pdf \"Document Title\" ~/Desktop /path/to/document.pdf\n\n# Use a specific blending strategy\nuvx mac-letterhead merge /path/to/letterhead.pdf \"Report\" ~/Desktop /path/to/report.pdf --strategy overlay\n```\n\n#### Markdown Processing  \n```bash\n# Convert Markdown with letterhead\nuvx mac-letterhead merge-md /path/to/letterhead.pdf \"Technical Guide\" ~/Desktop /path/to/guide.md\n\n# With custom CSS styling\nuvx mac-letterhead merge-md /path/to/letterhead.pdf \"Proposal\" ~/Desktop /path/to/proposal.md --css /path/to/styles.css\n```\n\n#### AI Integration with MCP Server\nMac-letterhead includes an MCP (Model Context Protocol) server that enables AI tools like Claude to create letterheaded PDFs through natural language commands:\n\n```bash\n# Start a generic multi-style server\nuvx mac-letterhead mcp\n\n# Start a dedicated single-style server  \nuvx mac-letterhead mcp --style easytocloud --output-dir ~/Documents/generated-pdfs\n```\n\n**Usage Examples with Claude:**\n- *\"Using the letterhead server, create an easytocloud style PDF about our new cloud services\"*\n- *\"Generate a personal letterheaded document for my consulting proposal\"*\n\nThe MCP server automatically:\n- Converts Markdown content to professionally formatted PDFs\n- Applies appropriate letterhead templates and CSS styling\n- Manages output directories and file naming\n- Supports both style-specific and generic multi-style configurations\n\nFor complete MCP setup and configuration details, see [README_MCP.md](README_MCP.md).\n\n### Blending Strategies\n\nChoose the optimal strategy for your letterhead design:\n\n- **`darken`** (Default): Ideal for light letterheads with dark text/logos - provides excellent readability\n- **`multiply`**: Creates watermark-like effects, good for subtle branding\n- **`overlay`**: Balances visibility of both document content and letterhead elements  \n- **`transparency`**: Smooth blending with semi-transparent effects\n- **`reverse`**: Places letterhead elements on top of document content\n\n## Advanced Features\n\n### Custom CSS Styling\n\nCreate sophisticated document styling by providing custom CSS:\n\n```css\n/* custom-styles.css */\nh1 { color: #2c5aa0; border-bottom: 2px solid #2c5aa0; }\ntable { border: 1px solid #ddd; background: #f9f9f9; }\ncode { background: #f4f4f4; padding: 2px 4px; }\n```\n\nThe CSS is automatically integrated with Mac-letterhead's smart margin system to ensure content fits properly within your letterhead design.\n\n### Markdown Features\n\nMac-letterhead provides professional Markdown rendering with:\n\n- **Typography**: Proper heading hierarchy, paragraph spacing, and font sizing\n- **Tables**: Clean borders, consistent padding, and professional appearance  \n- **Code Blocks**: Syntax highlighting for multiple programming languages\n- **Lists \u0026 Quotes**: Proper indentation and formatting for nested content\n- **Images \u0026 Links**: Full support for embedded images and hyperlinks\n- **Math**: LaTeX-style mathematical expressions (when supported)\n\n#### GitHub Flavored Markdown Support\n\nMac-letterhead includes enhanced support for GitHub Flavored Markdown (GFM) features:\n\n- **Strikethrough**: `~~deleted text~~` renders with proper strikethrough formatting\n- **Task Lists**: Interactive-style checkboxes with `- [x] completed` and `- [ ] pending`\n- **Enhanced Tables**: Improved table rendering with better alignment and styling\n- **Automatic Detection**: GFM features are automatically enabled when the pycmarkgfm library is available\n\nTask lists are rendered with professional Unicode checkboxes (☑ for completed, ☐ for pending) that are properly sized and aligned, including within table cells.\n\n### Dual Rendering Pipeline\n\nMac-letterhead features a sophisticated dual-backend rendering system that automatically selects the best available technology while providing manual control when needed.\n\n#### PDF Rendering Backends\n\n**WeasyPrint** (Preferred when available):\n- **Advantages**: Superior CSS support, advanced typography, precise layout control\n- **Features**: Full HTML5/CSS3 support, web fonts, complex layouts, print-specific CSS\n- **Requirements**: System libraries (`brew install pango cairo fontconfig freetype harfbuzz`)\n- **Use Case**: High-quality documents requiring advanced styling and typography\n\n**ReportLab** (Reliable fallback):\n- **Advantages**: Pure Python implementation, no system dependencies, consistent rendering\n- **Features**: Professional PDF generation, basic HTML support, reliable cross-platform operation\n- **Requirements**: None (included with Python installation)\n- **Use Case**: Simple documents, environments without system library access\n\n#### Markdown Processing Backends\n\n**GitHub Flavored Markdown (GFM)** (Enhanced when available):\n- **Library**: pycmarkgfm (Python bindings to GitHub's cmark-gfm parser)\n- **Features**: Strikethrough, task lists, enhanced tables, autolinks, GitHub-compatible parsing\n- **Compatibility**: Full compatibility with GitHub markdown rendering\n- **Use Case**: Documents with GFM-specific features, GitHub repository documentation\n\n**Standard Markdown** (Universal fallback):\n- **Library**: Python markdown with extensions\n- **Features**: CommonMark compliance, basic table support, code highlighting\n- **Compatibility**: Works in all Python environments\n- **Use Case**: Simple documents, maximum compatibility requirements\n\n#### Backend Selection and Control\n\n**Automatic Selection** (Default behavior):\n```bash\n# Uses best available backends automatically\nuvx mac-letterhead merge-md letterhead.pdf \"Document\" ~/Desktop document.md\n```\n\n**Manual Backend Control**:\n```bash\n# Force specific PDF backend\nuvx mac-letterhead merge-md letterhead.pdf \"Report\" ~/Desktop report.md --pdf-backend reportlab\n\n# Force specific Markdown backend  \nuvx mac-letterhead merge-md letterhead.pdf \"Guide\" ~/Desktop guide.md --markdown-backend standard\n\n# Combine specific backends\nuvx mac-letterhead merge-md letterhead.pdf \"Technical\" ~/Desktop tech.md --pdf-backend weasyprint --markdown-backend gfm\n```\n\n**Available Backend Options**:\n- `--pdf-backend`: `weasyprint`, `reportlab`, `auto` (default: `auto`)\n- `--markdown-backend`: `gfm`, `standard`, `auto` (default: `auto`)\n\n#### Backend Capabilities Matrix\n\n| Feature | WeasyPrint + GFM | WeasyPrint + Standard | ReportLab + GFM | ReportLab + Standard |\n|---------|------------------|----------------------|-----------------|---------------------|\n| Basic Markdown | ✅ Excellent | ✅ Excellent | ✅ Good | ✅ Good |\n| Advanced CSS | ✅ Full Support | ✅ Full Support | ⚠️ Limited | ⚠️ Limited |\n| Strikethrough | ✅ Native | ❌ Not Available | ✅ Unicode | ❌ Not Available |\n| Task Lists | ✅ Styled Checkboxes | ❌ Not Available | ✅ Unicode Checkboxes | ❌ Not Available |\n| Complex Tables | ✅ Advanced | ✅ Good | ✅ Basic | ✅ Basic |\n| Typography | ✅ Professional | ✅ Professional | ✅ Standard | ✅ Standard |\n| System Dependencies | ⚠️ Required | ⚠️ Required | ✅ None | ✅ None |\n\n#### Testing and Validation\n\nThe project includes comprehensive testing for all backend combinations:\n\n```bash\n# Test all combinations across Python versions\nmake test-backend-combinations\n\n# Test specific combinations\nmake test-weasyprint-gfm      # WeasyPrint + GitHub Flavored Markdown\nmake test-weasyprint-standard # WeasyPrint + Standard Markdown  \nmake test-reportlab-gfm       # ReportLab + GitHub Flavored Markdown\nmake test-reportlab-standard  # ReportLab + Standard Markdown\n```\n\nEach test combination generates output files with naming patterns like `document-py3.11-weasyprint-gfm.pdf` for easy comparison and quality validation.\n\n## Versioning \u0026 Publishing\n\nReleases are automated with [semantic-release](https://semantic-release.gitbook.io/) via GitHub Actions. Use Conventional Commit messages on `main` and the workflow will:\n\n- determine the next semantic version\n- update `letterhead_pdf/__init__.py`, `server.json`, `uv.lock`, and `CHANGELOG.md`\n- build the package and upload it to PyPI\n- create the GitHub release and tag\n\nCommit messages must follow the [Conventional Commits](https://www.conventionalcommits.org/) format so semantic-release can infer the correct version bump.\n\n### Local tooling (optional)\n\n1. Install once:\n   ```bash\n   npm install\n   ```\n2. Preview the next release without publishing:\n   ```bash\n   make release-dry-run\n   ```\n3. If you need to release from your workstation, provide your PyPI token and run:\n   ```bash\n   export TWINE_USERNAME=__token__\n   export TWINE_PASSWORD=...\n   make publish\n   ```\n\nThe GitHub Action uses the same configuration, so merging Conventional Commits into `main` is usually all that’s required.\n\n## Use Cases\n\n- **Corporate Communications**: Apply company branding to business correspondence\n- **Legal Documents**: Add firm letterhead and disclaimers to contracts and legal papers\n- **Financial Documents**: Brand invoices, statements, and financial reports\n- **Technical Documentation**: Convert Markdown documentation to branded PDFs  \n- **Academic Papers**: Add institutional letterhead to research papers and reports\n- **Proposals \u0026 Reports**: Create professional client deliverables from Markdown sources\n- **AI-Generated Content**: Use Claude or other AI tools to create branded documents through natural language\n\n## Troubleshooting\n\n### Common Issues\n\n**Library Dependencies**: If you see WeasyPrint warnings, the system automatically falls back to ReportLab - functionality is not affected.\n\n**File Permissions**: If applications request file access, approve the permissions in System Preferences \u003e Security \u0026 Privacy \u003e Privacy \u003e Files and Folders.\n\n**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.\n\n### Log Files\n- Application logs: `~/Library/Logs/Mac-letterhead/letterhead.log`\n- Droplet logs: `~/Library/Logs/Mac-letterhead/droplet.log`\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing procedures, and pull request guidelines.\n\n## License\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feasytocloud%2Fmac-letterhead","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feasytocloud%2Fmac-letterhead","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feasytocloud%2Fmac-letterhead/lists"}