This skill targets MarkItDown 0.1.6. The timeline below summarizes changes that affect user code and operational guidance.
Major architecture release:
--keep-data-uris addedBreaking changes:
[all] for behavior comparable to earlier all-in-one installs.convert_stream() now requires a binary stream.DocumentConverter implementations now receive binary streams plus StreamInfo, not file paths.convert_url() renamed to convert_uri().file: and data: URI handling added.convert_url() retained as a compatibility alias.defusedxmlMARKITDOWN_ENABLE_PLUGINSSecurity maintenance release:
pdfminer.six updated to address GHSA-wf5f-4jwr-ppcptext/markdown added to the HTTP Accept headerCreate a clean environment for the comparison:
uv venv --python 3.12 .venv-markitdown
source .venv-markitdown/bin/activate
uv pip install "markitdown[all]==0.1.6"
Do not test a migration in an environment that still contains unknown third-party plugins.
Old/compatibility:
content = result.text_content
Current:
content = result.markdown
text_content still works in 0.1.6 but is explicitly documented in source as a soft-deprecated alias.
Broad:
result = converter.convert(user_value)
Narrow local path:
result = converter.convert_local(validated_path)
Use convert_stream() for validated uploaded bytes and convert_response() after an application-controlled download.
Old:
from io import StringIO
result = converter.convert_stream(StringIO("text"))
Current:
from io import BytesIO
from markitdown import StreamInfo
result = converter.convert_stream(
BytesIO(b"text"),
stream_info=StreamInfo(
extension=".txt",
mimetype="text/plain",
charset="utf-8",
),
)
Old:
result = converter.convert_url(uri)
Current:
result = converter.convert_uri(validated_uri)
Prefer caller-controlled fetching plus convert_response() for HTTP(S).
Legacy:
result = converter.convert_stream(stream, file_extension=".pdf")
Current:
from markitdown import StreamInfo
result = converter.convert_stream(
stream,
stream_info=StreamInfo(
extension=".pdf",
mimetype="application/pdf",
filename="upload.pdf",
),
)
The legacy file_extension/url parameters still exist but are marked for migration in source.
Pre-0.1 converter:
class OldConverter(DocumentConverter):
def convert(self, file_path):
...
0.1.x converter:
from typing import Any, BinaryIO
from markitdown import DocumentConverter, DocumentConverterResult, StreamInfo
class CurrentConverter(DocumentConverter):
def accepts(
self,
file_stream: BinaryIO,
stream_info: StreamInfo,
**kwargs: Any,
) -> bool:
...
def convert(
self,
file_stream: BinaryIO,
stream_info: StreamInfo,
**kwargs: Any,
) -> DocumentConverterResult:
return DocumentConverterResult(markdown="...")
If accepts() peeks at bytes, restore the original stream position before returning.
Outdated entry-point group:
[project.entry-points."markitdown.plugins"]
Current group:
[project.entry-points."markitdown.plugin"]
example = "example_markitdown_plugin"
The plugin module must export:
__plugin_interface_version__ = 1
def register_converters(markitdown, **kwargs):
...
Use pyproject.toml; old setup.py-only examples are no longer the preferred packaging pattern.
Outdated:
uv pip install markitdown
uv pip install "markitdown[all]"
Repository-standard reproducible install:
uv pip install "markitdown[all]==0.1.6"
The base package no longer implies every format dependency. Select an extra or [all].
Remove these stale claims:
Current behavior:
markitdown-ocr==0.1.0 uses an external vision-capable client for embedded images and scanned-PDF page fallback.The official OCR plugin README's --llm-client/--llm-model CLI example is not accepted by the 0.1.6 core CLI parser. Configure the plugin in Python.
Current constructors accept explicit credentials:
MarkItDown(
docintel_endpoint="https://...",
docintel_credential=credential,
)
MarkItDown(
cu_endpoint="https://...",
cu_credential=credential,
)
Without an explicit credential, the 0.1.6 converters use the named AZURE_API_KEY if present and otherwise DefaultAzureCredential.
Do not rely on undocumented variable names such as AZURE_DOCUMENT_INTELLIGENCE_KEY for these constructors.
Content Understanding is new in 0.1.6:
from markitdown import MarkItDown
converter = MarkItDown(
cu_endpoint="https://...",
cu_analyzer_id="optional-custom-analyzer",
)
Replace:
convert(value) callsWith:
.text_content with .markdownconvert_url() with convert_uri() or controlled fetch