Synthkit

Production tools for working with AI — Markdown to PDF, DOCX, HTML, and email. Usable from the command line or as a Python library.

Looking for thinking tools? Structured exploration, strategic debate, CISO review, and codebase mapping have moved to thinkkit, a dedicated Claude Code plugin. Install with /plugin marketplace add https://github.com/rappdw/thinkkit then /plugin install thinkkit.

Installation

# Run directly with uvx (no install needed)
uvx synthkit html document.md

# Or install globally
uv tool install synthkit

# Or install with pip
pip install synthkit

Pandoc is bundled automatically via pypandoc_binary — no separate install needed.

Document Conversion

System dependencies for PDF

PDF conversion uses WeasyPrint, which requires system libraries:

Platform	Install command
macOS	brew install pango
Ubuntu/Debian	apt install libpango1.0-dev libcairo2-dev libgdk-pixbuf2.0-dev
Windows	See WeasyPrint docs

doc, html, and email commands work without these.

Usage

Unified CLI

synthkit doc report.md           # → report.docx
synthkit html report.md          # → report.html
synthkit pdf report.md           # → report.pdf
synthkit email report.md         # → clipboard

# Batch processing
synthkit doc *.md
synthkit html *.md --hard-breaks

# Mermaid diagrams (requires mermaid-filter)
synthkit html report.md --mermaid

Backward-compatible commands

md2doc report.md
md2html report.md
md2pdf report.md
md2email report.md

Options

Flag	Description
--hard-breaks	Preserve line breaks from source markdown
--mermaid	Enable Mermaid diagram rendering (requires mermaid-filter)

Configuration

Each converter looks for optional config files under ~/.config/<toolname>/:

Converter	Config Files
doc	~/.config/md2doc/reference.docx
email	~/.config/md2email/style.css
html	~/.config/md2html/style.css
pdf	~/.config/md2pdf/style.css

Testing

# Run tests
uv run --extra dev pytest

# With coverage
uv run --extra dev pytest --cov=synthkit --cov-report=term-missing

Tests run automatically on push/PR to main across Python 3.10-3.13 on Linux, macOS, and Windows.

Repository Structure

├── .github/workflows/
│   ├── tests.yml          # CI: test on push/PR to main
│   └── publish.yml        # CD: publish to PyPI on release
├── pyproject.toml
├── src/synthkit/          # Python package
│   ├── cli.py             # Click CLI with subcommands
│   ├── base.py            # Shared conversion logic
│   ├── doc.py             # Word conversion
│   ├── email.py           # Email clipboard conversion
│   ├── html.py            # HTML conversion
│   └── pdf.py             # PDF conversion (via WeasyPrint)
├── tests/                 # Test suite (pytest)
├── style.css              # Default stylesheet
├── prompt-templates/      # Pointers to canonical templates
└── guidelines/            # Reference standards

Dependencies

Package	Purpose	Bundled?
click	CLI framework	pip
pypandoc_binary	Pandoc document converter	pip (includes binary)
pyperclip	Cross-platform clipboard	pip
weasyprint	PDF engine	pip (needs system libs)
mermaid-filter	Mermaid diagrams	Optional, external