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
| Type |
Formats |
| Documents |
PDF, DOCX, PPTX, XLSX |
| Images |
PNG, JPG, JPEG, WEBP, TIFF |
| Web |
HTML (local), URLs (http/https) |
| Text |
TXT, MD, CSV, JSON, XML |
Key Options
| Option |
Purpose |
--format human |
Clean, readable output (default) |
--format rag |
Structured output for LLM/RAG |
--json |
Structured output for agents |
--input-dir |
Batch process entire directory |
--output-dir |
Output directory for batch mode |
--recursive |
Include subdirectories in batch |
--parallel N |
Process N files concurrently |
--frontmatter |
Add YAML metadata header |
--pdf-backend marker |
For scanned PDFs |
--pages 1-10 |
Convert specific pages only |
Workflow
- Check dependencies (auto-install if missing)
- Run:
python scripts/gateway.py --input <path> --json
- Check JSON
success field
- If
warnings present, consider switching backend
- 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 讀", "餵給模型", "向量資料庫"
| Format |
Output Style |
human |
## Title / Name (email) / clean links |
rag |
## **Title** / **Name** _email_ / full metadata |
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.
1---2name: document-to-markdown-23description: 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", "s4---56---7name: document-to-markdown8description: 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".9license: MIT License. See LICENSE.txt for details.10compatibility: macOS, Python 3.10+, curl11metadata:12 version: "1.0.0"13---1415# Document to Markdown1617Convert documents and URLs to clean Markdown for LLM/RAG use.1819## Prerequisites (Auto-handled)2021Before running any conversion, check and install dependencies if needed:2223```bash24# Check if dependencies are installed, install if missing25pip show pymupdf4llm markitdown pyyaml > /dev/null 2>&1 || pip install -r ~/.claude/skills/document-to-markdown/requirements.txt26```2728Run this check automatically before first use. Do not prompt user for installation.2930## Quick Start3132```bash33# Single file34python scripts/gateway.py --input <file_or_url> [--json]3536# Batch processing37python scripts/gateway.py --input-dir <folder> --output-dir <out> [--recursive] [--parallel 4]38```3940## Supported Inputs4142| Type | Formats |43|------|---------|44| Documents | PDF, DOCX, PPTX, XLSX |45| Images | PNG, JPG, JPEG, WEBP, TIFF |46| Web | HTML (local), URLs (http/https) |47| Text | TXT, MD, CSV, JSON, XML |4849## Key Options5051| Option | Purpose |52|--------|---------|53| `--format human` | Clean, readable output (default) |54| `--format rag` | Structured output for LLM/RAG |55| `--json` | Structured output for agents |56| `--input-dir` | Batch process entire directory |57| `--output-dir` | Output directory for batch mode |58| `--recursive` | Include subdirectories in batch |59| `--parallel N` | Process N files concurrently |60| `--frontmatter` | Add YAML metadata header |61| `--pdf-backend marker` | For scanned PDFs |62| `--pages 1-10` | Convert specific pages only |6364## Workflow65661. Check dependencies (auto-install if missing)672. Run: `python scripts/gateway.py --input <path> --json`683. Check JSON `success` field694. If `warnings` present, consider switching backend705. Read output file to present content to user7172## Format Selection7374Default: `--format human` (clean, readable for humans)7576Use `--format rag` when user prompt mentions:77- "for RAG", "for LLM", "for embedding", "for AI"78- "vector database", "chunking", "indexing"79- "給 AI 讀", "餵給模型", "向量資料庫"8081| Format | Output Style |82|--------|-------------|83| `human` | `## Title` / `Name (email)` / clean links |84| `rag` | `## **Title**` / `**Name** _email_` / full metadata |8586## Conditional Logic8788```89IF warning "Complex tables detected":90 → Retry with --pdf-backend marker (slower but better tables)9192IF output is empty or very short:93 → Retry with --pdf-backend marker (for scanned PDFs)9495IF URL timeout:96 → Increase --url-timeout or use --url-backend markitdown9798IF OCR quality poor:99 → Specify --lang for correct language100```101102## Output Format103104Single file:105```json106{"success": true, "output_path": "doc.md", "backend_used": "pymupdf4llm"}107```108109Batch:110```json111{"success": true, "total": 10, "converted": 9, "failed": 1, "results": [...]}112```113114For backend details, see `references/backends.md`.115For troubleshooting, see `references/troubleshooting.md`.
majiayu000