Docling - Document Conversion Skill

Convert any document format to structured Markdown, JSON, or HTML using IBM Docling with AI-powered layout analysis.

Quick Start

Batch convert directory to Markdown:

uv run python .claude/skills/docling/scripts/convert_docs.py \
  --input /path/to/documents \
  --output /path/to/output \
  --format md

Single file via CLI:

uv run docling document.pptx --to md --output ./output

Primary Use Case: Batch Conversion

The main script scripts/convert_docs.py handles:

Recursive directory scanning
Clean filename generation (slugified, numbered)
Index file creation with table of contents
Progress tracking

Example - Convert presentation course:

uv run python .claude/skills/docling/scripts/convert_docs.py \
  --input .artifacts/presentations \
  --output docs/course \
  --format md \
  --prefix "lesson"

Supported Formats

Input Formats

| Format | Extension | Notes | |--------|-----------|-------| | PowerPoint | .pptx | Slides extracted with structure | | PDF | .pdf | Layout analysis, OCR support | | Word | .docx | Full formatting preserved | | Excel | .xlsx | Tables converted | | HTML | .html | Structure preserved | | Images | .png, .jpg, .tiff | OCR extraction | | Audio | .wav, .mp3 | ASR transcription | | Markdown | .md | Pass-through with parsing | | CSV | .csv | Table structure |

Output Formats

| Format | Flag | Use Case | |--------|------|----------| | Markdown | --to md | Documentation, RAG | | JSON | --to json | Structured data, API | | HTML | --to html | Web publishing | | Text | --to text | Plain text extraction | | DocTags | --to doctags | Docling internal format |

CLI Reference

Basic Usage

# Single file
uv run docling document.pdf --to md

# Multiple files
uv run docling file1.pdf file2.docx --to md

# Directory
uv run docling ./documents/ --to md --output ./output/

# URL
uv run docling https://example.com/doc.pdf --to md

OCR Options

# Enable OCR (default: auto)
uv run docling scanned.pdf --ocr --ocr-engine tesseract

# Force OCR on all content
uv run docling document.pdf --force-ocr

# Specify language
uv run docling document.pdf --ocr-lang ukr,eng

OCR Engines: auto, easyocr, tesseract, tesserocr, rapidocr, ocrmac (macOS)

Table Extraction

# Accurate mode (slower, better quality)
uv run docling document.pdf --table-mode accurate

# Fast mode
uv run docling document.pdf --table-mode fast

# Disable tables
uv run docling document.pdf --no-tables

Image Handling

# Embed images as base64
uv run docling document.pdf --image-export-mode embedded

# Save images as separate files
uv run docling document.pdf --image-export-mode referenced

# Placeholder only (no images)
uv run docling document.pdf --image-export-mode placeholder

AI Enrichment

# Enable code block detection
uv run docling document.pdf --enrich-code

# Enable formula recognition
uv run docling document.pdf --enrich-formula

# Enable picture classification
uv run docling document.pdf --enrich-picture-classification

# Enable picture description (VLM)
uv run docling document.pdf --enrich-picture-description

VLM Pipeline (Vision Language Model)

# Use VLM for complex documents
uv run docling document.pdf --pipeline vlm --vlm-model granite_docling

# Available models: granite_docling, smoldocling, got_ocr_2, granite_vision

ASR Pipeline (Audio Transcription)

# Transcribe audio
uv run docling audio.mp3 --pipeline asr --asr-model whisper_small

# Models: whisper_tiny, whisper_small, whisper_medium, whisper_large, whisper_turbo

Performance Options

# Multi-threading
uv run docling document.pdf --num-threads 8

# GPU acceleration
uv run docling document.pdf --device cuda  # or mps for Apple Silicon

# Timeout per document
uv run docling document.pdf --document-timeout 300

Python API

Basic Conversion

from docling.document_converter import DocumentConverter

converter = DocumentConverter()
result = converter.convert("document.pptx")

# Export to Markdown
markdown = result.document.export_to_markdown()

# Export to JSON
json_data = result.document.export_to_dict()

# Save directly
result.document.save_as_markdown("output.md")

Batch Conversion

from pathlib import Path
from docling.document_converter import DocumentConverter

converter = DocumentConverter()
sources = list(Path("./documents").glob("*.pdf"))

for result in converter.convert_all(sources):
    if result.status.name == "SUCCESS":
        output = Path("./output") / f"{result.input.file.stem}.md"
        result.document.save_as_markdown(output)

With Pipeline Options

from docling.document_converter import DocumentConverter, FormatOption
from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import PdfPipelineOptions

pdf_options = PdfPipelineOptions(
    do_ocr=True,
    do_table_structure=True,
    table_structure_options={"mode": "accurate"},
)

converter = DocumentConverter(
    format_options={
        InputFormat.PDF: FormatOption(pipeline_options=pdf_options)
    }
)

Chunking for RAG

from docling.document_converter import DocumentConverter
from docling.chunking import HybridChunker

converter = DocumentConverter()
result = converter.convert("document.pdf")

chunker = HybridChunker()
chunks = list(chunker.chunk(result.document))

for chunk in chunks:
    print(f"Chunk: {chunk.text[:100]}...")

Troubleshooting

| Problem | Solution | |---------|----------| | No text extracted | Enable OCR: --ocr or --force-ocr | | Tables not formatted | Use --table-mode accurate | | Slow processing | Use --table-mode fast, reduce --num-threads | | Memory errors | Reduce --page-batch-size, process files individually |

Debug Options

uv run docling document.pdf -v     # info logging
uv run docling document.pdf -vv    # debug logging
uv run docling document.pdf --debug-visualize-layout  # see layout detection

Resources

scripts/

convert_docs.py - Batch conversion with clean filenames and index generation