
docling
Docling document parser for PDF, DOCX, PPTX, HTML, images, and 15+ formats. Use when parsing documents, extracting text, converting to Markdown/HTML/JSON, chunking for RAG pipelines, or batch processing files. Triggers on DocumentConverter, convert, convertall, exporttomarkdown, HierarchicalChunker, HybridChunker, ConversionResult.
- Installs
- 431
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/existential-birds/beagle --skill docling- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads docling automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Docling Document Parser
Docling is a document parsing library that converts PDFs, Word documents, PowerPoint, images, and other formats into structured data with advanced layout understanding.
Quick Start
Basic document conversion:
from docling.document_converter import DocumentConverter
source = "https://arxiv.org/pdf/2408.09869" # URL, Path, or BytesIO
converter = DocumentConverter()
result = converter.convert(source)
print(result.document.export_to_markdown())
Core Concepts
DocumentConverter
The main entry point for document conversion. Supports various input formats and conversion options.
from docling.document_converter import DocumentConverter
from docling.datamodel.base_models import InputFormat
from docling.document_converter import PdfFormatOption
from docling.datamodel.pipeline_options import PdfPipelineOptions
# Basic converter (all formats enabled)
converter = DocumentConverter()
# Restricted formats
converter = DocumentConverter(
allowed_formats=[InputFormat.PDF, InputFormat.DOCX]
)
# Custom pipeline options
pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = True
pipeline_options.do_table_structure = True
converter = DocumentConverter(
format_options={
InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)
}
)
ConversionResult
All conversion operations return a ConversionResult containing:
document: The parsedDoclingDocumentstatus:ConversionStatus.SUCCESS,PARTIAL_SUCCESS, orFAILUREerrors: List of errors encountered during conversioninput: Information about the source document
from docling.datamodel.base_models import ConversionStatus
result = converter.convert("document.pdf")
if result.status == ConversionStatus.SUCCESS:
markdown = result.document.export_to_markdown()
html = result.document.export_to_html()
data = result.document.export_to_dict()
Supported Formats
Input Formats
- Documents: PDF, DOCX, PPTX, XLSX
- Markup: HTML, Markdown, AsciiDoc
- Data: CSV, JSON (Docling format)
- Images: PNG, JPEG, TIFF, BMP, WEBP
- Audio: WAV, MP3
- Video Text: WebVTT
- Schema-specific: USPTO XML, JATS XML, METS-GBS
Output Formats
- Markdown:
export_to_markdown()orsave_as_markdown() - HTML:
export_to_html()orsave_as_html() - JSON:
export_to_dict()orsave_as_json()(note: noexport_to_json()method) - Text:
export_to_text()orexport_to_markdown(strict_text=True)orsave_as_markdown(strict_text=True) - DocTags:
export_to_doctags()orsave_as_doctags()
Common Patterns
Single File Conversion
from docling.document_converter import DocumentConverter
converter = DocumentConverter()
result = converter.convert("document.pdf")
# Export to different formats
markdown = result.document.export_to_markdown()
html = result.document.export_to_html()
json_data = result.document.export_to_dict()
# Or save directly to file
result.document.save_as_markdown("output.md")
result.document.save_as_html("output.html")
result.document.save_as_json("output.json")
Batch Processing
See references/batch.md for details on convert_all().
URL Conversion
converter = DocumentConverter()
result = converter.convert("https://example.com/document.pdf")
Binary Stream Conversion
from io import BytesIO
from docling.datamodel.base_models import DocumentStream
with open("document.pdf", "rb") as f:
buf = BytesIO(f.read())
source = DocumentStream(name="document.pdf", stream=buf)
result = converter.convert(source)
Format-Specific Options
from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import PdfPipelineOptions
from docling.document_converter import DocumentConverter, PdfFormatOption
# Configure PDF-specific options
pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = True
pipeline_options.ocr_options.lang = ["en", "es"]
pipeline_options.do_table_structure = True
pipeline_options.generate_page_images = True
converter = DocumentConverter(
format_options={
InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)
}
)
Resource Limits
converter = DocumentConverter()
# Limit file size (bytes) and page count
result = converter.convert(
"large_document.pdf",
max_file_size=20_971_520, # 20 MB
max_num_pages=100
)
Document Chunking
See references/chunking.md for RAG integration.
DoclingDocument Structure
The DoclingDocument is a Pydantic model representing parsed content:
# Access document structure
doc = result.document
# Content items (lists)
doc.texts # TextItem instances (paragraphs, headings, etc.)
doc.tables # TableItem instances
doc.pictures # PictureItem instances
doc.key_value_items # Key-value pairs
# Structure (tree nodes)
doc.body # Main content hierarchy
doc.furniture # Headers, footers, page numbers
doc.groups # Lists, chapters, sections
# Iterate all elements in reading order
for item, level in doc.iterate_items():
print(f"{' ' * level}{item.label}: {item.text[:50]}")
Advanced Features
OCR Configuration
from docling.datamodel.pipeline_options import (
PdfPipelineOptions,
EasyOcrOptions,
TesseractOcrOptions,
TesseractCliOcrOptions,
OcrMacOptions,
RapidOcrOptions
)
# EasyOCR (default)
pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = True
pipeline_options.ocr_options = EasyOcrOptions(lang=["en", "de"])
# Tesseract
pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = True
pipeline_options.ocr_options = TesseractOcrOptions(lang=["eng", "deu"])
# RapidOCR
pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = True
pipeline_options.ocr_options = RapidOcrOptions()
Table Extraction Options
from docling.datamodel.pipeline_options import (
PdfPipelineOptions,
TableFormerMode
)
pipeline_options = PdfPipelineOptions()
pipeline_options.do_table_structure = True
# Use cell matching (map to PDF cells)
pipeline_options.table_structure_options.do_cell_matching = True
# Or use predicted cells
pipeline_options.table_structure_options.do_cell_matching = False
# Choose accuracy mode
pipeline_options.table_structure_options.mode = TableFormerMode.ACCURATE
Page Images
pipeline_options = PdfPipelineOptions()
pipeline_options.generate_page_images = True # Needed for HTML export with images
# Export with embedded images
result.document.save_as_html(
"output.html",
image_mode=ImageRefMode.EMBEDDED
)
Error Handling
from docling.datamodel.base_models import ConversionStatus
result = converter.convert("document.pdf")
if result.status == ConversionStatus.SUCCESS:
print("Conversion successful")
elif result.status == ConversionStatus.PARTIAL_SUCCESS:
print("Partial conversion:")
for error in result.errors:
print(f" {error.error_message}")
else: # FAILURE
print("Conversion failed:")
for error in result.errors:
print(f" {error.error_message}")
For batch processing with error handling:
# Continue processing on errors
results = converter.convert_all(
["doc1.pdf", "doc2.pdf", "doc3.pdf"],
raises_on_error=False
)
for result in results:
if result.status == ConversionStatus.SUCCESS:
result.document.save_as_markdown(f"{result.input.file.stem}.md")
else:
print(f"Failed: {result.input.file}")
Gates
Before treating output as complete or feeding it downstream (RAG, evals, storage):
- Obtain
resultfromconvert()or follow batch sequencing in references/batch.md. - Pass:
result.statusisConversionStatus.SUCCESS, orPARTIAL_SUCCESSand you have readresult.errorsand explicitly accept partial output for the task, orFAILUREis handled (no export/chunking on failure unless intended). - Only then call
export_to_*,save_as_*, or chunkers in references/chunking.md.
For convert_all: Pass when each input maps to a result and each result.status is classified before writing outputs (see references/batch.md).
CLI Usage
# Basic conversion
docling document.pdf
# Convert to specific output
docling --to markdown document.pdf
# With custom model path
docling --artifacts-path /path/to/models document.pdf
# Using VLM pipeline
docling --pipeline vlm --vlm-model granite_docling document.pdf
Reference Documentation
- Parsing Options - DocumentConverter initialization, format-specific options, OCR configuration
- Batch Processing - convert_all(), error handling, concurrency patterns
- Chunking - HierarchicalChunker, HybridChunker, RAG integration
- Output Formats - export_to_markdown(), export_to_html(), export_to_dict(), document structure
Key Types
DocumentConverter: Main conversion classConversionResult: Result of conversion with document and statusDoclingDocument: Unified document representation (Pydantic model)InputFormat: Enum of supported input formatsConversionStatus: SUCCESS, PARTIAL_SUCCESS, FAILUREPdfPipelineOptions: Configuration for PDF pipelineImageRefMode: EMBEDDED, REFERENCED, PLACEHOLDER
Integration Examples
LangChain
from docling.document_converter import DocumentConverter
from langchain_text_splitters import MarkdownTextSplitter
converter = DocumentConverter()
result = converter.convert("document.pdf")
markdown = result.document.export_to_markdown()
splitter = MarkdownTextSplitter(chunk_size=1000)
chunks = splitter.split_text(markdown)
LlamaIndex
from docling.document_converter import DocumentConverter
from docling.chunking import HybridChunker
from llama_index.core import Document
converter = DocumentConverter()
result = converter.convert("document.pdf")
chunker = HybridChunker()
chunks = list(chunker.chunk(result.document))
documents = [
Document(text=chunk.text, metadata=chunk.meta.export_json_dict())
for chunk in chunks
]
Notes
- Docling uses a synchronous API (no native async support)
- Models are downloaded automatically on first use (can be prefetched)
- Supports local execution for air-gapped environments
- Supports GPU acceleration for OCR and table detection
- Default models run on CPU; GPU requires configuration
FAQ
What does the docling skill do?
Docling document parser for PDF, DOCX, PPTX, HTML, images, and 15+ formats. Use when parsing documents, extracting text, converting to Markdown/HTML/JSON, chunking for RAG pipelines, or batch processing files. Triggers on DocumentConverter, convert, convertall, exporttomarkdown, HierarchicalChunker, HybridChunker, ConversionResult.
How do I install docling?
Run npx skills add https://github.com/existential-birds/beagle --skill docling in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/docling/ (personal) or .claude/skills/docling/ (project).
Which AI agents can use docling?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is docling safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains docling?
It is published by existential-birds in existential-birds/beagle. It has 431 recorded installs.
More from existential-birds/beagle
react-flow
existential-birds/beagle
React Flow (@xyflow/react) for workflow visualization with custom nodes and edges. Use when building graph visualizations, creating custom workflow nodes, implementing edge labels, or controlling viewport. Triggers on ReactFlow, @xyflow/react, Handle, NodeProps, EdgeProps, useReactFlow, fitView.
python-code-review
existential-birds/beagle
Reviews Python code for type safety, async patterns, error handling, and common mistakes. Use when reviewing .py files, checking type hints, async/await usage, or exception handling.
langgraph-code-review
existential-birds/beagle
Reviews LangGraph code for bugs, anti-patterns, and improvements. Use when reviewing code that uses StateGraph, nodes, edges, checkpointing, or other LangGraph features. Catches common mistakes in state management, graph structure, and async patterns.
tailwind-v4
existential-birds/beagle
Tailwind CSS v4 with CSS-first configuration and design tokens. Use when setting up Tailwind v4, defining theme variables, using OKLCH colors, or configuring dark mode. Triggers on @theme, @tailwindcss/vite, oklch, CSS variables, --color-, tailwind v4.
react-flow-advanced
existential-birds/beagle
Advanced React Flow patterns for complex use cases. Use when implementing sub-flows, custom connection lines, programmatic layouts, drag-and-drop, undo/redo, or complex state synchronization.
react-router-v7
existential-birds/beagle
React Router v7 best practices for data-driven routing. Use when implementing routes, loaders, actions, Form components, fetchers, navigation guards, protected routes, or URL search params. Triggers on createBrowserRouter, RouterProvider, useLoaderData, useActionData, useFetcher, NavLink, Outlet.
Popular docs & writing skills
grill-with-docs
mattpocock/skills
A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
lark-markdown
open.feishu.cn
飞书 Markdown:查看、创建、上传、编辑和比较飞书中的原生 Markdown 文件。当用户要操作飞书 Markdown 文件,或比较其远端版本及本地草稿时使用。纯本地 Markdown 文件操作不触发本 skill。不负责将 Markdown 导入为飞书在线文档,也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。
writing-beats
mattpocock/skills
Writing, exploit; assemble raw material into a journey of beats, grounding each term before a beat leans on it.
writing-shape
mattpocock/skills
Writing, exploit: shape raw material into an article, paragraph by paragraph.
writing-fragments
mattpocock/skills
Writing, explore: mine raw fragments, no structure yet.
writing-for-agents
mattpocock/skills
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.