Document to Markdown

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.