tomd-converter 0.1.0

Universal file-to-Markdown converter — optimized for AI consumption.

tomd

Convert any file to clean Markdown — optimized for AI consumption.

tomd is an all-in-one CLI tool that converts 15+ file formats into token-efficient, structure-preserving Markdown. Feed documents, spreadsheets, presentations, images, audio, and even YouTube videos to your favourite LLM without wasting context window on noisy formatting.

Quick Start

# Install core (PDF, DOCX, PPTX, HTML, CSV, JSON, XML, XLSX, EPUB, text, ZIP)
pip install tomd-converter

# Optional extras
pip install tomd-converter[ocr]      # Image EXIF + OCR (Pillow, pytesseract)
pip install tomd-converter[audio]    # Audio metadata + transcription (mutagen, Vosk)
pip install tomd-converter[youtube]  # YouTube metadata + subtitles (yt-dlp)
pip install tomd-converter[all]      # Everything

Usage

# Single file → stdout (pipe to clipboard, AI tool, etc.)
tomd report.pdf
tomd report.pdf | xclip -selection clipboard

# Save to file
tomd document.docx -o output.md

# Batch convert
tomd *.pdf
tomd ./documents/

# YouTube
tomd "https://youtube.com/watch?v=dQw4w9WgXcQ"

# Options
tomd file.pdf --no-meta          # Skip YAML frontmatter
tomd large.csv --max-rows 100    # Truncate tables
tomd --list-formats              # Show supported formats

Supported Formats

Format	Extensions	Extra
PDF	.pdf	core
Word	.docx	core
PowerPoint	.pptx	core
Excel	.xlsx, .xls	core
HTML	.html, .htm	core
EPUB	.epub	core
CSV/TSV	.csv, .tsv	core
JSON	.json, .jsonl	core
XML/SVG	.xml, .svg	core
Plain text	.txt, .log, .md	core
Source code	.py, .js, .rs, …	core
ZIP	.zip	core
Images	.jpg, .png, .webp, …	[ocr]
Audio	.mp3, .wav, .flac, …	[audio]
YouTube	URL	[youtube]

Output Format

tomd produces clean, AI-friendly Markdown with minimal YAML frontmatter:

---
source: quarterly_report.pdf
type: pdf
title: Q4 Financial Report
---

# Q4 Financial Report

Revenue increased by 15% year-over-year…

| Metric | Q3 | Q4 |
| --- | --- | --- |
| Revenue | $10M | $11.5M |
| Profit | $2M | $2.8M |

Why tomd?

• 🤖 AI-optimized — Clean output, minimal frontmatter, no wasted tokens
• 📦 All-in-one — One tool for PDFs, docs, spreadsheets, images, audio, video
• 🔌 Extensible — Plugin architecture, easy to add new formats
• ⚡ Fast — Lazy dependency loading, only imports what you need
• 🛡️ Robust — Graceful fallbacks, never crashes on bad input

License

MIT