Skip to content

GuruDevvv/my-claude-skills / external/doc-to-markdown

doc-to-markdown

Verified

Converts DOCX/PDF/PPTX to high-quality Markdown with automatic post-processing. Fixes pandoc grid tables, simple tables, image paths, CJK bold spacing, attribute noise, and code blocks. Benchmarked best-in-class (7.6/10) against Docling, MarkItDown, Pandoc raw, and Mammoth. Trigger on "convert document", "docx to markdown", "parse word", "doc to markdown", "解析word", "转换文档".

references/tool-comparison.md

View on GitHub
# Tool Comparison

Comparison of document-to-markdown conversion tools.

## Feature Matrix

| Feature | pymupdf4llm | markitdown | pandoc |
|---------|-------------|------------|--------|
| **PDF Support** | ✅ Excellent | ✅ Good | ⚠️ Limited |
| **DOCX Support** | ❌ No | ✅ Good | ✅ Excellent |
| **PPTX Support** | ❌ No | ✅ Good | ✅ Good |
| **XLSX Support** | ❌ No | ✅ Good | ⚠️ Limited |
| **Table Detection** | ✅ Multiple strategies | ⚠️ Basic | ✅ Good |
| **Image Extraction** | ✅ With metadata | ❌ No | ✅ Yes |
| **Heading Hierarchy** | ✅ Good | ⚠️ Variable | ✅ Excellent |
| **List Formatting** | ✅ Good | ⚠️ Basic | ✅ Excellent |
| **LLM Optimization** | ✅ Built-in | ❌ No | ❌ No |

## Installation

### pymupdf4llm

```bash
pip install pymupdf4llm

# Or with uv
uv pip install pymupdf4llm
```

**Dependencies:** None (pure Python with PyMuPDF)

### markitdown

```bash
# All formats — [all] is required: [pdf] alone fails on .pptx and .xlsx
uv tool install "markitdown[all]"

# Or
pip install "markitdown[all]"
```

**Dependencies:** Various per format (pdfminer, python-docx, etc.)

### pandoc

```bash
# macOS
brew install pandoc

# Ubuntu/Debian
apt-get install pandoc

# Windows
choco install pandoc
```

**Dependencies:** System installation required

## Performance Benchmarks

### PDF Conversion (100-page document)

| Tool | Time | Memory | Output Quality |
|------|------|--------|----------------|
| pymupdf4llm | ~15s | 150MB | Excellent |
| markitdown | ~45s | 200MB | Good |
| pandoc | ~60s | 100MB | Variable |

### DOCX Conversion (50-page document)

| Tool | Time | Memory | Output Quality |
|------|------|--------|----------------|
| pandoc | ~5s | 50MB | Excellent |
| markitdown | ~10s | 80MB | Good |

## Best Practices

### For PDFs

1. **First choice:** pymupdf4llm
   - Best table detection
   - Image extraction with metadata
   - LLM-optimized output

2. **Fallback:** markitdown
   - When pymupdf4llm fails
   - Simpler documents

### For DOCX/DOC

1. **First choice:** pandoc
   - Best structure preservation
   - Proper heading hierarchy
   - List formatting

2. **Fallback:** markitdown
   - When pandoc unavailable
   - Quick conversion needed

### For PPTX

1. **First choice:** markitdown
   - Good slide content extraction
   - Handles speaker notes

2. **Fallback:** pandoc
   - Better structure preservation

### For XLSX

1. **Only option:** markitdown
   - Table to markdown conversion
   - Sheet handling

## Common Issues by Tool

### pymupdf4llm

| Issue | Solution |
|-------|----------|
| "Cannot import fitz" | `pip install pymupdf` |
| Tables not detected | Try different `table_strategy` |
| Images not extracted | Enable `write_images=True` |

### markitdown

| Issue | Solution |
|-------|----------|
| PDF support missing | Install with `[pdf]` extra |
| Slow conversion | Expected for large files |
| Missing content | Try alternative tool |

### pandoc

| Issue | Solution |
|-------|----------|
| Command not found | Install via package manager |
| PDF conversion fails | Use pymupdf4llm instead |
| Images not extracted | Add `--extract-media` flag |

## API Comparison

### pymupdf4llm

```python
import pymupdf4llm

md = pymupdf4llm.to_markdown(
    "doc.pdf",
    write_images=True,
    table_strategy="lines_strict",
    image_path="./assets"
)
```

### markitdown

```python
from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("document.pdf")
print(result.text_content)
```

### pandoc

```bash
pandoc document.docx -t markdown --wrap=none --extract-media=./assets
```

```python
import subprocess

result = subprocess.run(
    ["pandoc", "doc.docx", "-t", "markdown", "--wrap=none"],
    capture_output=True, text=True
)
print(result.stdout)
```
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall