# Extension points — microsoft/markitdown

> Canonical page: https://codevetter.com/unpack/markitdown/extension-points

# Extension points — microsoft/markitdown

Scanned commit b8f79c57ebc0044be41323d89b2a45d3fda8460e (2026-09-21). Generated by codevetter codevetter 1.12.0 on 2026-09-22.

MarkItDown is explicitly designed for extension at two levels: in-process registration via MarkItDown.register_converter(converter, priority=...) and distribution-level plugins via the 'markitdown.plugin' entry-point group. Converters subclass DocumentConverter and implement accepts()/convert(); several built-ins expose finer hooks (DocxConverter._image_to_html, style_map, llm_* kwargs). The markitdown-ocr package is the canonical example of a plugin that overrides built-ins by registering with negative priority.
- register_converter(converter, *, priority=PRIORITY_SPECIFIC_FILE_FORMAT) inserts a ConverterRegistration at index 0 of self._converters; docstring documents that equal priorities preserve registration order with most-recent-first, and that plugins can pick priorities (e.g., 9) to slot between specific and generic converters. — [packages/markitdown/src/markitdown/_markitdown.py#L709-739](https://github.com/microsoft/markitdown/blob/b8f79c57ebc0044be41323d89b2a45d3fda8460e/packages/markitdown/src/markitdown/_markitdown.py#L709-L739)
- Plugin contract: a package declares [project.entry-points."markitdown.plugin"] name = 'module', the module defines __plugin_interface_version__ = 1 and register_converters(markitdown, **kwargs) which calls markitdown.register_converter(...). — [packages/markitdown-sample-plugin/pyproject.toml](https://github.com/microsoft/markitdown/blob/b8f79c57ebc0044be41323d89b2a45d3fda8460e/packages/markitdown-sample-plugin/pyproject.toml) [packages/markitdown-sample-plugin/src/markitdown_sample_plugin/_plugin.py#L13-31](https://github.com/microsoft/markitdown/blob/b8f79c57ebc0044be41323d89b2a45d3fda8460e/packages/markitdown-sample-plugin/src/markitdown_sample_plugin/_plugin.py#L13-L31)
- markitdown-ocr demonstrates priority-based replacement: it registers its four converters at priority -1.0 so they run before all built-ins at 0.0, and its *WithOCR classes subclass the built-in converters so inherits tests verify drop-in compatibility. — [packages/markitdown-ocr/src/markitdown_ocr/_plugin.py#L49-68](https://github.com/microsoft/markitdown/blob/b8f79c57ebc0044be41323d89b2a45d3fda8460e/packages/markitdown-ocr/src/markitdown_ocr/_plugin.py#L49-L68) [packages/markitdown-ocr/tests/test_docx_inheritance.py](https://github.com/microsoft/markitdown/blob/b8f79c57ebc0044be41323d89b2a45d3fda8460e/packages/markitdown-ocr/tests/test_docx_inheritance.py)
- New converters plug in by subclassing DocumentConverter and implementing accepts(file_stream, stream_info, **kwargs)->bool and convert(...)->DocumentConverterResult; the docstrings document that accepts() must restore the stream position if it reads. — [packages/markitdown/src/markitdown/_base_converter.py#L42-105](https://github.com/microsoft/markitdown/blob/b8f79c57ebc0044be41323d89b2a45d3fda8460e/packages/markitdown/src/markitdown/_base_converter.py#L42-L105)
- DocxConverter._image_to_html is an overridable hook: if a subclass overrides it, convert() wires a _DocxImages adapter into mammoth's convert_image callback so subclasses can render embedded images as custom HTML fragments. — [packages/markitdown/src/markitdown/converters/_docx_converter.py#L105-143](https://github.com/microsoft/markitdown/blob/b8f79c57ebc0044be41323d89b2a45d3fda8460e/packages/markitdown/src/markitdown/converters/_docx_converter.py#L105-L143)
- Global kwargs llm_client, llm_model, llm_prompt, style_map, and exiftool_path are injected into every converter call by _convert(), letting callers extend behavior (e.g., captions, custom docx style maps) without subclassing. — [packages/markitdown/src/markitdown/_markitdown.py#L630-657](https://github.com/microsoft/markitdown/blob/b8f79c57ebc0044be41323d89b2a45d3fda8460e/packages/markitdown/src/markitdown/_markitdown.py#L630-L657)
- _parent_converters is passed through kwargs so container converters (ZipConverter holds a MarkItDown reference; epub/docx delegate to HtmlConverter) can recurse with the full registry — a nested-conversion extension channel. — [packages/markitdown/src/markitdown/_markitdown.py#L648-649](https://github.com/microsoft/markitdown/blob/b8f79c57ebc0044be41323d89b2a45d3fda8460e/packages/markitdown/src/markitdown/_markitdown.py#L648-L649) [packages/markitdown/src/markitdown/converters/_zip_converter.py#L61-67](https://github.com/microsoft/markitdown/blob/b8f79c57ebc0044be41323d89b2a45d3fda8460e/packages/markitdown/src/markitdown/converters/_zip_converter.py#L61-L67)
- _CustomMarkdownify subclasses markdownify.MarkdownConverter, so any markdownify option can be passed through kwargs from converters that emit HTML (HtmlConverter, DocxConverter, EpubConverter, RssConverter, etc.). — [packages/markitdown/src/markitdown/converters/_markdownify.py#L25-39](https://github.com/microsoft/markitdown/blob/b8f79c57ebc0044be41323d89b2a45d3fda8460e/packages/markitdown/src/markitdown/converters/_markdownify.py#L25-L39) [packages/markitdown/src/markitdown/converters/_html_converter.py#L93-110](https://github.com/microsoft/markitdown/blob/b8f79c57ebc0044be41323d89b2a45d3fda8460e/packages/markitdown/src/markitdown/converters/_html_converter.py#L93-L110)
- Cloud converters are opt-in registrations: passing docintel_endpoint/cu_endpoint (+credential/file_types/analyzer_id kwargs) to MarkItDown() registers DocumentIntelligenceConverter/ContentUnderstandingConverter at default priority, effectively a DI-based extension point. — [packages/markitdown/src/markitdown/_markitdown.py#L254-296](https://github.com/microsoft/markitdown/blob/b8f79c57ebc0044be41323d89b2a45d3fda8460e/packages/markitdown/src/markitdown/_markitdown.py#L254-L296)
- register_page_converter() remains as a deprecated alias emitting DeprecationWarning, showing the registration API is the stable public seam. — [packages/markitdown/src/markitdown/_markitdown.py#L701-707](https://github.com/microsoft/markitdown/blob/b8f79c57ebc0044be41323d89b2a45d3fda8460e/packages/markitdown/src/markitdown/_markitdown.py#L701-L707)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)