AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

markitdown

Converts heterogeneous documents and selected URIs to Markdown with Microsoft MarkItDown for text analysis, search, and LLM/RAG ingestion. Covers safe local conversion, streams, Office/PDF/data formats, batch workflows, plugins, vision OCR, Azure extraction, and the official MCP server.

Original source
K-Dense-AI
License
MIT
Pinned revision
5f2bc0341354fd5590aef76a533ada1e1e5b4e62

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read k-dense-ai--markitdown at revision 5f2bc0341354fd5590aef76a533ada1e1e5b4e62, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 8

references/migration.md

Migration and Release Notes

This skill targets MarkItDown 0.1.8. The timeline below summarizes changes that affect user code and operational guidance.

Release Timeline

0.1.0 — March 22, 2025

Major architecture release:

  • Optional dependency feature groups introduced
  • Plugin architecture introduced
  • Conversions moved to in-memory streams; temporary files removed
  • EPUB support added
  • CLI extension, MIME, and charset hints added
  • --keep-data-uris added

Breaking changes:

  • Install [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.

0.1.1 — March 25, 2025

  • convert_url() renamed to convert_uri().
  • file: and data: URI handling added.
  • convert_url() retained as a compatibility alias.

0.1.2 — May 28, 2025

  • DOCX math-equation rendering
  • Dedicated CSV-to-Markdown conversion
  • XML/OMML parsing switched to defusedxml
  • Document Intelligence credential/API-version improvements
  • Streamable HTTP MCP support
  • YouTube transcript fixes
  • Python requirement updated to 3.10+

0.1.3 — August 26, 2025

  • Safer ExifTool handling, requiring version 12.24 or later
  • MCP plugin enablement through MARKITDOWN_ENABLE_PLUGINS
  • DOCX linked-image fixes
  • Document Intelligence HTML type handling
  • Custom LLM prompt forwarding fix
  • Additional HTML/PPTX robustness

0.1.4 — December 1, 2025

Security maintenance release:

  • Mammoth updated to address CVE-2025-11849
  • pdfminer.six updated to address GHSA-wf5f-4jwr-ppcp

0.1.5 — February 20, 2026

  • Better aligned and wide PDF tables
  • Partially numbered PDF-list fix
  • text/markdown added to the HTTP Accept header
  • Windows ONNX Runtime pin removed

0.1.6 — May 26, 2026

  • Official OCR layer/plugin for embedded images and scanned PDFs
  • PDF page cleanup to fix linear memory growth
  • Deeply nested HTML recursion fix
  • Azure Content Understanding converter
  • Expanded security guidance for broad I/O and MCP binding

0.1.7 and 0.1.8 — maintenance through September 21, 2026

  • Python supports >=3.10,<3.15.
  • Document Intelligence defers API version selection to its SDK instead of hardcoding the old preview.
  • CU uses the SDK to_llm_input() helper and requires azure-ai-contentunderstanding>=1.2.0b1; see the preview-default caveat in cloud_and_ocr.md.
  • CLI cloud endpoints can come from MARKITDOWN_DOCINTEL_ENDPOINT and MARKITDOWN_CU_ENDPOINT; stdin is buffered before detection.
  • CSV preserves wider rows and CR-only lines; notebook BOM/headings, RSS/Atom links/content, and duplicate ZIP member handling improved.
  • markitdown-ocr==0.1.1 uses core Office image hooks and needs core >=0.1.8.
  • markitdown-mcp==0.0.1a7 uses MCP SDK 2.x.
  • URI schemes are case-insensitive; file: rejects UNC/device paths. Local path authorization is still the caller's responsibility.

Upgrade Installation

Create 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.8"

Do not test a migration in an environment that still contains unknown third-party plugins.

Code Replacements

Result content

Old/compatibility:

content = result.text_content

Current:

content = result.markdown

text_content still works in 0.1.8 but is explicitly documented in source as a soft-deprecated alias.

Local conversion

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.

Streams

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",
    ),
)

URI API

Old:

result = converter.convert_url(uri)

Current:

result = converter.convert_uri(validated_uri)

Prefer caller-controlled fetching plus convert_response() for HTTP(S).

Hints

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.

Custom Converter Migration

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.

Plugin Packaging Migration

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.

Installation Guidance Migration

Outdated:

uv pip install markitdown
uv pip install "markitdown[all]"

Repository-standard reproducible install:

uv pip install "markitdown[all]==0.1.8"

The base package no longer implies every format dependency. Select an extra or [all].

OCR Guidance Migration

Remove these stale claims:

  • "Built-in PDF conversion uses Tesseract"
  • "All images are OCR'd locally"
  • "GIF and WebP are handled by the built-in image converter"

Current behavior:

  • Built-in PDF extracts an existing text layer.
  • Built-in JPEG/PNG conversion extracts metadata and optionally requests an LLM description.
  • markitdown-ocr==0.1.1 uses an external vision-capable client for embedded images and scanned-PDF page fallback.
  • Azure Document Intelligence and Content Understanding provide cloud OCR/extraction.

The official OCR plugin README's --llm-client/--llm-model CLI example is not accepted by the 0.1.8 core CLI parser. Configure the plugin in Python.

Azure Migration

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.8 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",
)

Security Migration

Replace:

  • User-controlled convert(value) calls
  • Broad URI access
  • Automatic plugin enablement
  • Undisclosed LLM/cloud fallback
  • Secrets embedded in examples
  • MCP binding to non-local interfaces

With:

  • Narrow conversion APIs
  • Path and destination allowlists
  • Explicit size/time/resource limits
  • Reviewed, pinned, opt-in plugins
  • User-approved external processing
  • Named credentials through secure provider configuration
  • STDIO or localhost-only MCP in a sandbox

Regression Checklist

  • [ ] Install 0.1.8 in a clean environment
  • [ ] Replace .text_content with .markdown
  • [ ] Replace text streams with binary streams
  • [ ] Replace convert_url() with convert_uri() or controlled fetch
  • [ ] Update custom converter signatures
  • [ ] Update plugin entry-point group
  • [ ] Pin format extras
  • [ ] Test PDF tables and multi-column reading order
  • [ ] Test DOCX math and linked images
  • [ ] Test PPTX grouped shapes and notes
  • [ ] Confirm plugins remain disabled by default
  • [ ] Confirm no conversion unexpectedly calls network/cloud
  • [ ] Compare semantic output on a representative corpus

Sources

  • Releases: https://github.com/microsoft/markitdown/releases
  • 0.1.0 migration notes: https://github.com/microsoft/markitdown/releases/tag/v0.1.0
  • 0.1.6 release: https://github.com/microsoft/markitdown/releases/tag/v0.1.6
  • 0.1.8 release: https://github.com/microsoft/markitdown/releases/tag/v0.1.8