Document To Markdown

name: document-to-markdown description: Convert PDF, Office, images, HTML, and URLs to Markdown. Use for document conversion, text extraction, OCR, web scraping, RAG pipelines. Triggers: "convert to markdown", "extract text", "read PDF", "scrape URL". license: MIT License. See LICENSE.txt for details. compatibility: macOS, Python 3.10+, curl metadata: version: "1.0.0"

Document to Markdown

Convert documents and URLs to clean Markdown for LLM/RAG use.

Prerequisites (Auto-handled)

Before running any conversion, check and install dependencies if needed:

# Check if dependencies are installed, install if missing
pip show pymupdf4llm markitdown pyyaml > /dev/null 2>&1 || pip install -r ~/.claude/skills/document-to-markdown/requirements.txt

Run this check automatically before first use. Do not prompt user for installation.

Quick Start

# Single file
python scripts/gateway.py --input <file_or_url> [--json]

# Batch processing
python scripts/gateway.py --input-dir <folder> --output-dir <out> [--recursive] [--parallel 4]

Supported Inputs

Key Options

Workflow

1. Check dependencies (auto-install if missing)
2. Run: python scripts/gateway.py --input <path> --json
3. Check JSON success field
4. If warnings present, consider switching backend
5. Read output file to present content to user

Format Selection

Default: --format human (clean, readable for humans)

Use --format rag when user prompt mentions:

• "for RAG", "for LLM", "for embedding", "for AI"
• "vector database", "chunking", "indexing"
• "給 AI 讀", "餵給模型", "向量資料庫"

Conditional Logic

IF warning "Complex tables detected":
  → Retry with --pdf-backend marker (slower but better tables)

IF output is empty or very short:
  → Retry with --pdf-backend marker (for scanned PDFs)

IF URL timeout:
  → Increase --url-timeout or use --url-backend markitdown

IF OCR quality poor:
  → Specify --lang for correct language

Output Format

Single file:

{"success": true, "output_path": "doc.md", "backend_used": "pymupdf4llm"}

Batch:

{"success": true, "total": 10, "converted": 9, "failed": 1, "results": [...]}

For backend details, see references/backends.md. For troubleshooting, see references/troubleshooting.md.