---

name: conversion description: "Use Docling's Python conversion API for local paths, URLs, streams, and in-memory Markdown/HTML/DocLang strings, including safe smoke conversions and failure handling." disable-model-invocation: true metadata: disco-role: operating license: MIT

Conversion

Use this sub-skill when a task needs Python API conversion into a DoclingDocument with DocumentConverter, convert, convert_all, convert_string, or DocumentStream.

Route elsewhere when the task is mainly about:

• CLI commands, supported format tables, or shell recipes: cli-and-formats.
• Export formats, Markdown/JSON/HTML serialization strategy, or chunking: document-outputs.
• OCR, table structure, PDF model options, accelerator settings, or artifacts paths: pipeline-configuration.
• VLM, ASR, remote model services, or advanced backends: advanced-pipelines.
• Structured data extraction with DocumentExtractor: extraction.

Fast Path

from docling.document_converter import DocumentConverter

converter = DocumentConverter()
result = converter.convert("document.pdf")  # local path or URL
markdown = result.document.export_to_markdown()

For string content, do not pass the raw string to convert; use convert_string with a supported InputFormat:

from docling.datamodel.base_models import InputFormat
from docling.document_converter import DocumentConverter

converter = DocumentConverter(allowed_formats=[InputFormat.MD])
result = converter.convert_string("# Title\n\nBody", format=InputFormat.MD, name="note.md")

References

• references/api-reference.md for constructor signatures, source types, limits, headers, batch conversion, and status handling.
• references/workflows.md for copy-ready local path, URL, stream, string, batch, and smoke-test recipes.
• references/troubleshooting.md for optional dependency, model download, wrong format option, headers, file limit, invalid path, and raises_on_error failures.
• scripts/convert_fixture.py for a safe installed-package helper that converts a caller-supplied path or string to Markdown or JSON.

Safety Defaults

• Prefer allowed_formats=[...] for smoke tests and user-controlled uploads so accidental format detection cannot trigger heavier pipelines.
• Use max_num_pages, max_file_size, and page_range for PDFs or untrusted documents.
• Use raises_on_error=False when collecting partial batch results; inspect result.status and result.errors before exporting.
• Expect first PDF/image conversions to download model artifacts unless the environment has prefetched models.