| name | pdftomd |
| description | Convert PDF and office documents (DOCX, PPTX, XLSX, HTML) to Markdown by automatically choosing the best tool among Pandoc, Marker, and MarkItDown based on layout complexity, math/equations, and file format strengths. |
| version | 1.0.0 |
| tags | ["pdf","markdown","converter","pandoc","marker","markitdown"] |
Document-to-Markdown (pdftomd) Conversion Skill
This skill provides decision logic, installation details, code snippets, and a helper script to convert PDF and various document formats into clean Markdown for LLM parsing, RAG pipelines, or document editing. It leverages the relative strengths of three primary tools: Pandoc, Marker, and MarkItDown.
1. Relative Strength Matrix
Choose the best tool for conversion by analyzing the input document structure, layout, and complexity:
| Feature / Format | Pandoc | Marker (marker-pdf) | MarkItDown | Recommended Choice |
|---|
| Text-Based (Single Column) PDFs | Fair (requires pdftotext first) | Excellent (high accuracy) | Excellent (very fast & clean) | MarkItDown (lightweight/fast) |
| Complex PDFs (Multi-column/Layouts) | Poor | Excellent (restructures columns) | Fair (may merge columns incorrectly) | Marker |
| Math & Equations (PDF) | Poor | Excellent (converts to LaTeX math) | Poor (extracts text chunks) | Marker |
| Scanned PDFs / OCR | Poor | Excellent (native Tesseract/EasyOCR) | Poor (no native image OCR) | Marker |
Word Documents (.docx) | Excellent (very clean headers/tables) | N/A (PDF only) | Excellent (easy API) | Pandoc (cleaner nested structures) |
Excel Spreadsheets (.xlsx) | Fair (converts to basic tables) | N/A (PDF only) | Excellent (cleans cells to MD tables) | MarkItDown |
PowerPoint Slides (.pptx) | Fair | N/A (PDF only) | Excellent (slides-to-text sections) | MarkItDown |
HTML / E-books (.epub) | Excellent (highly customizable) | N/A | Fair | Pandoc |
2. Decision Flow
[Input File Type?]
/ \
[PDF] [Office / Text Docs]
/ \ / | \
[Math/Scanned] [Standard text] [DOCX] [XLSX] [Other]
/ \ / | \
(Marker) (MarkItDown) (Pandoc) (MarkItDown) (Pandoc)
3. Tool Installation
3.1 Pandoc
Pandoc is a compiled binary.
3.2 Marker
Marker relies on PyTorch and layout models. It requires Python 3.9+ and PyTorch.
pip install marker-pdf
Note: Depending on system configurations, you may also need to install system dependencies such as Tesseract-OCR and ghostscript for scanned PDF support.
3.3 MarkItDown
Microsoft's lightweight converter can be installed directly from PyPI.
pip install markitdown
4. Usage Recipes & CLI Examples
4.1 Using the Helper Script (Automatic Selection)
A helper script is provided at skills/pdftomd/scripts/convert.py to automate the selection of the best available tool based on the criteria above:
python skills/pdftomd/scripts/convert.py input.pdf -o output.md
python skills/pdftomd/scripts/convert.py paper.pdf -o output.md --pdf-type math
python skills/pdftomd/scripts/convert.py document.docx -o output.md --tool pandoc
4.2 Raw Tool Command Snippets
Pandoc (for clean DOCX/HTML structure)
pandoc -f docx -t gfm input.docx -o output.md
Marker (for complex/scanned PDFs)
marker_single input.pdf --output_dir output_folder/
MarkItDown (via Python API)
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("input.xlsx")
with open("output.md", "w", encoding="utf-8") as f:
f.write(result.text_content)
5. Developer & Integration Guidelines
- Metadata Preservation: Always extract and append document metadata (author, title, creation date) at the top of the converted Markdown file as a frontmatter block where possible.
- Layout and Spacing: After conversion, inspect for artifacts such as hyphenation split across lines (e.g.,
docu-\nment) and remove them.
- Spreadsheets: Excel tables converted to Markdown can be extremely wide. Recommend utilizing MarkItDown for spreadsheet extractions, and consider transposing tables if the column count exceeds 8 columns to ensure model readability.
