ContextQMD
Back to Claude Scientific Skills

MarkItDown 0.1.6 API Reference

skills/markitdown/references/api_reference.md

2.55.011.2 KB
Original Source

MarkItDown 0.1.6 API Reference

Verified against the v0.1.6 source tag and installed package on July 23, 2026.

Public Imports

python
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:

python
from markitdown.converters import (
    ContentUnderstandingFileType,
    DocumentIntelligenceFileType,
)

MarkItDown

Constructor

python
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:

KeywordPurpose
requests_sessionCustom requests.Session used by HTTP(S) URI conversion
llm_clientOpenAI-compatible client for image descriptions and compatible plugins
llm_modelProvider-specific model identifier
llm_promptPrompt for image description/OCR
exiftool_pathExplicit trusted ExifTool executable
style_mapMammoth style map for DOCX conversion
docintel_endpointEnable Azure Document Intelligence
docintel_credentialExplicit AzureKeyCredential or token credential
docintel_file_typesRestrict Document Intelligence routing
docintel_api_versionAzure Document Intelligence API version
cu_endpointEnable Azure Content Understanding
cu_credentialExplicit AzureKeyCredential or token credential
cu_analyzer_idCustom Content Understanding analyzer
cu_file_typesRestrict Content Understanding routing

The public signature uses **kwargs; spell these names exactly.

Conversion methods

convert()

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

Dispatch rules:

  • str beginning with http:, https:, file:, or data: → 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()

python
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.

python
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()

python
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.
python
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()

python
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()

python
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

python
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:

python
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

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

Attributes and conversions:

InterfaceStatus
result.markdownCanonical converted Markdown
result.titleOptional source-derived title
result.text_contentSoft-deprecated alias for markdown
str(result)Returns markdown
python
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:

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

Common options:

OptionUsed by
keep_data_urisHTML/Markdown conversion; preserve rather than truncate data URIs
youtube_transcript_languagesYouTube transcript language preference
llm_client, llm_model, llm_promptImage/PPTX description and compatible plugins
style_mapDOCX conversion
exiftool_pathImage/audio metadata

Exceptions

python
from markitdown import (
    FileConversionException,
    MissingDependencyException,
    UnsupportedFormatException,
)
ExceptionMeaning
MissingDependencyExceptionThe converter matched, but its optional dependency is unavailable
UnsupportedFormatExceptionNo registered converter accepted the source
FileConversionExceptionOne or more matching converters attempted and failed
TypeErrorconvert() received an unsupported source type, such as a text stream
python
from markitdown import (
    FileConversionException,
    MarkItDown,
    MissingDependencyException,
    UnsupportedFormatException,
)

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

Converter Registration

python
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():

python
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:

python
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:

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

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

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

CLI Reference

text
markitdown [options] [filename]

If filename is omitted, MarkItDown reads binary input from stdin.

OptionMeaning
-v, --versionPrint package version
-o, --output PATHWrite UTF-8 Markdown to a file
-x, --extension EXTFile-extension hint
-m, --mime-type TYPEMIME-type hint
-c, --charset NAMECharset hint
-d, --use-docintelUse Azure Document Intelligence
-e, --endpoint URLDocument Intelligence endpoint
--use-cu, --use-content-understandingUse Azure Content Understanding
--cu-endpoint URLContent Understanding endpoint
--cu-analyzer IDCustom analyzer ID
--cu-file-types LISTComma-separated CU file types
-p, --use-pluginsEnable installed third-party plugins
--list-pluginsList discovered plugins and exit
--keep-data-urisPreserve full data URIs

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

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

Source Basis