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/api_reference.md

MarkItDown 0.1.8 API Reference

Verified against the v0.1.8 source tag and installed package on October 1, 2026.

Public Imports

from markitdown import (
    DocumentConverter,
    DocumentConverterResult,
    FileConversionException,
    MarkItDown,
    MissingDependencyException,
    PRIORITY_GENERIC_FILE_FORMAT,
    PRIORITY_SPECIFIC_FILE_FORMAT,
    StreamInfo,
    UnsupportedFormatException,
)

Azure file-type enums are exported from markitdown.converters:

from markitdown.converters import (
    ContentUnderstandingFileType,
    DocumentIntelligenceFileType,
)

MarkItDown

Constructor

MarkItDown(
    *,
    enable_builtins: bool | None = None,
    enable_plugins: bool | None = None,
    **kwargs,
)

Built-in converters are enabled by default. Third-party plugins are disabled by default.

Recognized constructor keywords include:

| Keyword | Purpose | |---|---| | requests_session | Custom requests.Session used by HTTP(S) URI conversion | | llm_client | OpenAI-compatible client for image descriptions and compatible plugins | | llm_model | Provider-specific model identifier | | llm_prompt | Prompt for image description/OCR | | exiftool_path | Explicit trusted ExifTool executable | | style_map | Mammoth style map for DOCX conversion | | docintel_endpoint | Enable Azure Document Intelligence | | docintel_credential | Explicit AzureKeyCredential or token credential | | docintel_file_types | Restrict Document Intelligence routing | | docintel_api_version | Azure Document Intelligence API version | | cu_endpoint | Enable Azure Content Understanding | | cu_credential | Explicit AzureKeyCredential or token credential | | cu_analyzer_id | Custom Content Understanding analyzer | | cu_file_types | Restrict Content Understanding routing |

The public signature uses **kwargs; spell these names exactly. Unknown names can be silently ignored: there is no cu_api_version option. docintel_api_version=None delegates to the installed Azure SDK default. See cloud_and_ocr.md for the tested SDK versions and network contracts.

Conversion methods

convert()

convert(
    source: str | Path | requests.Response | BinaryIO,
    *,
    stream_info: StreamInfo | None = None,
    **kwargs,
) -> DocumentConverterResult

Dispatch rules:

  • str with a parsed http:, https:, file:, or data: scheme (case-insensitive) → convert_uri()
  • other str or Path → convert_local()
  • requests.Response → convert_response()
  • binary file-like object → convert_stream()
  • text stream → TypeError

This convenience method is broad. Prefer a narrower method for untrusted or application-facing inputs.

convert_local()

convert_local(
    path: str | Path,
    *,
    stream_info: StreamInfo | None = None,
    file_extension: str | None = None,
    url: str | None = None,
    **kwargs,
) -> DocumentConverterResult

file_extension and url are legacy parameters; put overrides in StreamInfo.

from pathlib import Path

from markitdown import MarkItDown

source = Path("experiment.xlsx")
result = MarkItDown().convert_local(source)
Path("experiment.md").write_text(result.markdown, encoding="utf-8")

convert_stream()

convert_stream(
    stream: BinaryIO,
    *,
    stream_info: StreamInfo | None = None,
    file_extension: str | None = None,
    url: str | None = None,
    **kwargs,
) -> DocumentConverterResult

Requirements and behavior:

  • The stream must be binary.
  • A seekable stream is preferred.
  • A non-seekable stream is copied completely into an in-memory BytesIO.
  • file_extension and url are legacy hints; prefer StreamInfo.
from io import BytesIO

from markitdown import MarkItDown, StreamInfo

payload = b"sample,value\ncontrol,1\ntreated,2\n"
result = MarkItDown().convert_stream(
    BytesIO(payload),
    stream_info=StreamInfo(
        extension=".csv",
        mimetype="text/csv",
        charset="utf-8",
        filename="results.csv",
    ),
)
print(result.markdown)

convert_uri()

convert_uri(
    uri: str,
    *,
    stream_info: StreamInfo | None = None,
    file_extension: str | None = None,
    mock_url: str | None = None,
    **kwargs,
) -> DocumentConverterResult

Supported schemes:

  • file: with an empty authority or localhost
  • data:
  • http:
  • https:

HTTP(S) conversion uses the configured requests.Session, follows Requests defaults, and then buffers the complete response in memory. It does not provide an application-level SSRF policy, download-size limit, or redirect allowlist. Validate and fetch remote resources yourself before calling convert_response().

convert_url() remains a backward-compatible alias, but new code should use convert_uri().

convert_response()

convert_response(
    response: requests.Response,
    *,
    stream_info: StreamInfo | None = None,
    file_extension: str | None = None,
    url: str | None = None,
    **kwargs,
) -> DocumentConverterResult

The method derives hints from Content-Type, Content-Disposition, and the response URL, then buffers every response chunk into memory. The caller is responsible for destination validation, redirect handling, timeout, maximum size, authentication, and TLS policy.

StreamInfo

StreamInfo(
    *,
    mimetype: str | None = None,
    extension: str | None = None,
    charset: str | None = None,
    filename: str | None = None,
    local_path: str | None = None,
    url: str | None = None,
)

Examples:

pdf_info = StreamInfo(
    mimetype="application/pdf",
    extension=".pdf",
    filename="paper.pdf",
)

html_info = StreamInfo(
    mimetype="text/html",
    extension=".html",
    charset="utf-8",
    filename="article.html",
)

Hints are merged with extension, HTTP header, and Magika content-detection guesses. If a caller-supplied hint conflicts with content detection, MarkItDown may try both guesses.

DocumentConverterResult

DocumentConverterResult(
    markdown: str,
    *,
    title: str | None = None,
)

Attributes and conversions:

| Interface | Status | |---|---| | result.markdown | Canonical converted Markdown | | result.title | Optional source-derived title | | result.text_content | Soft-deprecated alias for markdown | | str(result) | Returns markdown |

result = MarkItDown().convert_local("paper.pdf")
markdown = result.markdown
title = result.title

Per-conversion Options

Converter-specific values can be forwarded through a conversion call:

result = converter.convert_local(
    "page.html",
    keep_data_uris=False,
)

Common options:

| Option | Used by | |---|---| | keep_data_uris | HTML/Markdown conversion; preserve rather than truncate data URIs | | youtube_transcript_languages | YouTube transcript language preference | | llm_client, llm_model, llm_prompt | Image/PPTX description and compatible plugins | | style_map | DOCX conversion | | exiftool_path | Image/audio metadata |

Exceptions

from markitdown import (
    FileConversionException,
    MissingDependencyException,
    UnsupportedFormatException,
)

| Exception | Meaning | |---|---| | MissingDependencyException | The converter matched, but its optional dependency is unavailable | | UnsupportedFormatException | No registered converter accepted the source | | FileConversionException | One or more matching converters attempted and failed | | TypeError | convert() received an unsupported source type, such as a text stream |

from markitdown import (
    FileConversionException,
    MarkItDown,
    MissingDependencyException,
    UnsupportedFormatException,
)

try:
    result = MarkItDown().convert_local("input.pdf")
except MissingDependencyException:
    print("Install markitdown[pdf]==0.1.8")
except UnsupportedFormatException:
    print("No converter accepted this input")
except FileConversionException as exc:
    print(f"A matching converter failed: {exc}")

Converter Registration

register_converter(
    converter: DocumentConverter,
    *,
    priority: float = PRIORITY_SPECIFIC_FILE_FORMAT,
) -> None

Lower numeric priorities run first. The built-in specific-format priority is 0.0; generic converters use 10.0. For registrations with equal priority, the most recently registered converter is attempted first.

register_page_converter() is deprecated.

Custom Converter

Version 0.1.x converters operate on binary streams and implement both accepts() and convert():

from typing import Any, BinaryIO

from markitdown import (
    DocumentConverter,
    DocumentConverterResult,
    StreamInfo,
)


class RtfConverter(DocumentConverter):
    def accepts(
        self,
        file_stream: BinaryIO,
        stream_info: StreamInfo,
        **kwargs: Any,
    ) -> bool:
        return (stream_info.extension or "").lower() == ".rtf"

    def convert(
        self,
        file_stream: BinaryIO,
        stream_info: StreamInfo,
        **kwargs: Any,
    ) -> DocumentConverterResult:
        raw = file_stream.read()
        # Replace this placeholder with a real, bounded RTF parser.
        return DocumentConverterResult(
            markdown=f"```text\n{raw.decode('utf-8', errors='replace')}\n```"
        )

Do not advance the stream in accepts(). If inspection is necessary, save the position with tell() and restore it with seek().

Plugin Package Contract

The plugin module exports interface version 1 and a registration function:

from markitdown import MarkItDown

__plugin_interface_version__ = 1


def register_converters(markitdown: MarkItDown, **kwargs) -> None:
    markitdown.register_converter(RtfConverter())

Register the module through pyproject.toml:

[project.entry-points."markitdown.plugin"]
example = "example_markitdown_plugin"

Inspect and install a trusted, pinned plugin, then verify discovery:

markitdown --list-plugins
markitdown --use-plugins input.rtf -o output.md

CLI Reference

markitdown [options] [filename]

If filename is omitted, MarkItDown buffers all binary stdin in memory before detection. Document Intelligence mode requires a filename; CU accepts hinted stdin.

| Option | Meaning | |---|---| | -v, --version | Print package version | | -o, --output PATH | Write UTF-8 Markdown to a file | | -x, --extension EXT | File-extension hint | | -m, --mime-type TYPE | MIME-type hint | | -c, --charset NAME | Charset hint | | -d, --use-docintel | Use Azure Document Intelligence | | -e, --endpoint URL | Document Intelligence endpoint; fallback MARKITDOWN_DOCINTEL_ENDPOINT | | --use-cu, --use-content-understanding | Use Azure Content Understanding | | --cu-endpoint URL | Content Understanding endpoint; fallback MARKITDOWN_CU_ENDPOINT | | --cu-analyzer ID | Custom analyzer ID | | --cu-file-types LIST | Comma-separated CU file types | | -p, --use-plugins | Enable installed third-party plugins | | --list-plugins | List discovered plugins and exit | | --keep-data-uris | Preserve full data URIs |

Document Intelligence and Content Understanding are mutually exclusive in one CLI invocation.

The core 0.1.8 parser does not expose --llm-client or --llm-model. Configure image descriptions or the OCR plugin through Python.

Source Basis

  • v0.1.8 package API: https://github.com/microsoft/markitdown/tree/v0.1.8/packages/markitdown/src/markitdown
  • v0.1.8 CLI: https://github.com/microsoft/markitdown/blob/v0.1.8/packages/markitdown/src/markitdown/main.py
  • v0.1.8 sample plugin: https://github.com/microsoft/markitdown/tree/v0.1.8/packages/markitdown-sample-plugin