# microsoft/markitdown architecture

> Architecture diagram of the GitHub repository microsoft/markitdown, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/markitdown
- Repository: https://github.com/microsoft/markitdown
- Video tour (about a minute): https://gitdiagram.com/microsoft/markitdown/video

## Overview

MarkItDown accepts local files, streams, and URLs, identifies their format, dispatches to a converter, and returns Markdown. The core includes format-specific extraction plus optional cloud analyzers, web/media conversion, and plugins; the OCR plugin augments Office and PDF conversion with LLM vision. The README documents these capabilities, while the MCP package is visible in the tree and its entry point references the core. Some converter implementations and MCP behavior were not excerpted, so their internal links are intentionally limited.

Main entry points: [`packages/markitdown/src/markitdown/_markitdown.py`](https://github.com/microsoft/markitdown/blob/main/packages/markitdown/src/markitdown/_markitdown.py) (Conversion engine), [`packages/markitdown/src/markitdown/converters/__init__.py`](https://github.com/microsoft/markitdown/blob/main/packages/markitdown/src/markitdown/converters/__init__.py) (Converter registry), [`packages/markitdown/src/markitdown/_base_converter.py`](https://github.com/microsoft/markitdown/blob/main/packages/markitdown/src/markitdown/_base_converter.py) (Markdown result), [`packages/markitdown-ocr/src/markitdown_ocr/_plugin.py`](https://github.com/microsoft/markitdown/blob/main/packages/markitdown-ocr/src/markitdown_ocr/_plugin.py) (OCR registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Input and dispatch"]
  node_engine["Conversion engine<br/>[_markitdown.py]"]
  node_metadata["Stream metadata<br/>[_stream_info.py]"]
  node_converter_api["Converter contract<br/>[_base_converter.py]"]
  node_registry["Converter registry<br/>[__init__.py]"]
  node_result["Markdown result<br/>[_base_converter.py]"]
end

subgraph group_formats["Built-in conversion"]
  node_office["Office formats"]
  node_pdf["PDF conversion<br/>[_pdf_converter.py]"]
  node_web["Web and feeds"]
  node_media["Images and audio"]
  node_text["Text and archives"]
end

subgraph group_cloud["Cloud analysis"]
  node_document_intel["Document Intelligence"]
  node_content_understanding["Content Understanding<br/>[_cu_converter.py]"]
end

subgraph group_plugins["OCR plugin"]
  node_ocr_plugin["OCR registration<br/>[_plugin.py]"]
  node_ocr_pdf["PDF OCR"]
  node_ocr_docx["DOCX OCR"]
  node_ocr_pptx["PPTX OCR"]
  node_ocr_xlsx["XLSX OCR"]
  node_ocr_service["LLM vision OCR<br/>[_ocr_service.py]"]
end

subgraph group_interfaces["User interfaces"]
  node_cli["Command line<br/>[__main__.py]"]
  node_mcp["MCP server<br/>[__main__.py]"]
end

node_user(("Caller"))
node_cloud_service(("Azure services"))
node_vision_model(("Vision API"))

node_user -->|"runs"| node_cli
node_user -->|"calls"| node_engine
node_user -.->|"uses"| node_mcp
node_cli -->|"invokes"| node_engine
node_mcp -->|"imports"| node_engine
node_engine -->|"builds"| node_metadata
node_engine -->|"dispatches"| node_registry
node_engine -->|"registers"| node_converter_api
node_registry -->|"exports"| node_office
node_registry -->|"exports"| node_pdf
node_registry -->|"exports"| node_web
node_registry -->|"exports"| node_media
node_registry -->|"exports"| node_text
node_engine -->|"registers"| node_document_intel
node_engine -->|"registers"| node_content_understanding
node_document_intel -->|"requests analysis"| node_cloud_service
node_content_understanding -->|"requests analysis"| node_cloud_service
node_engine -->|"loads optionally"| node_ocr_plugin
node_ocr_plugin -->|"registers"| node_ocr_pdf
node_ocr_plugin -->|"registers"| node_ocr_docx
node_ocr_plugin -->|"registers"| node_ocr_pptx
node_ocr_plugin -->|"registers"| node_ocr_xlsx
node_ocr_pdf -->|"extracts text"| node_ocr_service
node_ocr_docx -->|"extracts text"| node_ocr_service
node_ocr_service -->|"sends image"| node_vision_model
node_engine -->|"returns Markdown"| node_result
node_office -->|"produces Markdown"| node_result
node_pdf -->|"produces Markdown"| node_result
node_web -->|"produces Markdown"| node_result
node_media -->|"produces Markdown"| node_result
node_text -->|"produces Markdown"| node_result

click node_cli "https://github.com/microsoft/markitdown/blob/main/packages/markitdown/src/markitdown/__main__.py"
click node_mcp "https://github.com/microsoft/markitdown/blob/main/packages/markitdown-mcp/src/markitdown_mcp/__main__.py"
click node_engine "https://github.com/microsoft/markitdown/blob/main/packages/markitdown/src/markitdown/_markitdown.py"
click node_metadata "https://github.com/microsoft/markitdown/blob/main/packages/markitdown/src/markitdown/_stream_info.py"
click node_converter_api "https://github.com/microsoft/markitdown/blob/main/packages/markitdown/src/markitdown/_base_converter.py"
click node_registry "https://github.com/microsoft/markitdown/blob/main/packages/markitdown/src/markitdown/converters/__init__.py"
click node_result "https://github.com/microsoft/markitdown/blob/main/packages/markitdown/src/markitdown/_base_converter.py"
click node_office "https://github.com/microsoft/markitdown/tree/main/packages/markitdown/src/markitdown/converters"
click node_pdf "https://github.com/microsoft/markitdown/blob/main/packages/markitdown/src/markitdown/converters/_pdf_converter.py"
click node_web "https://github.com/microsoft/markitdown/tree/main/packages/markitdown/src/markitdown/converters"
click node_media "https://github.com/microsoft/markitdown/tree/main/packages/markitdown/src/markitdown/converters"
click node_text "https://github.com/microsoft/markitdown/tree/main/packages/markitdown/src/markitdown/converters"
click node_document_intel "https://github.com/microsoft/markitdown/blob/main/packages/markitdown/src/markitdown/converters/_doc_intel_converter.py"
click node_content_understanding "https://github.com/microsoft/markitdown/blob/main/packages/markitdown/src/markitdown/converters/_cu_converter.py"
click node_ocr_plugin "https://github.com/microsoft/markitdown/blob/main/packages/markitdown-ocr/src/markitdown_ocr/_plugin.py"
click node_ocr_pdf "https://github.com/microsoft/markitdown/blob/main/packages/markitdown-ocr/src/markitdown_ocr/_pdf_converter_with_ocr.py"
click node_ocr_docx "https://github.com/microsoft/markitdown/blob/main/packages/markitdown-ocr/src/markitdown_ocr/_docx_converter_with_ocr.py"
click node_ocr_pptx "https://github.com/microsoft/markitdown/blob/main/packages/markitdown-ocr/src/markitdown_ocr/_pptx_converter_with_ocr.py"
click node_ocr_xlsx "https://github.com/microsoft/markitdown/blob/main/packages/markitdown-ocr/src/markitdown_ocr/_xlsx_converter_with_ocr.py"
click node_ocr_service "https://github.com/microsoft/markitdown/blob/main/packages/markitdown-ocr/src/markitdown_ocr/_ocr_service.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_engine,node_metadata,node_converter_api,node_registry,node_result toneBlue
class node_office,node_pdf,node_web,node_media,node_text toneAmber
class node_document_intel,node_content_understanding,node_vision_model toneMint
class node_ocr_plugin,node_ocr_pdf,node_ocr_docx,node_ocr_pptx,node_ocr_xlsx,node_ocr_service toneRose
class node_cli,node_mcp,node_user,node_cloud_service toneIndigo
```

## Components

### Input and dispatch

- [Conversion engine](https://github.com/microsoft/markitdown/blob/main/packages/markitdown/src/markitdown/_markitdown.py): `packages/markitdown/src/markitdown/_markitdown.py`
- [Stream metadata](https://github.com/microsoft/markitdown/blob/main/packages/markitdown/src/markitdown/_stream_info.py): `packages/markitdown/src/markitdown/_stream_info.py`
- [Converter contract](https://github.com/microsoft/markitdown/blob/main/packages/markitdown/src/markitdown/_base_converter.py): `packages/markitdown/src/markitdown/_base_converter.py`
- [Converter registry](https://github.com/microsoft/markitdown/blob/main/packages/markitdown/src/markitdown/converters/__init__.py): `packages/markitdown/src/markitdown/converters/__init__.py`
- [Markdown result](https://github.com/microsoft/markitdown/blob/main/packages/markitdown/src/markitdown/_base_converter.py): `packages/markitdown/src/markitdown/_base_converter.py`

### Built-in conversion

- [Office formats](https://github.com/microsoft/markitdown/tree/main/packages/markitdown/src/markitdown/converters): `packages/markitdown/src/markitdown/converters`
- [PDF conversion](https://github.com/microsoft/markitdown/blob/main/packages/markitdown/src/markitdown/converters/_pdf_converter.py): `packages/markitdown/src/markitdown/converters/_pdf_converter.py`
- [Web and feeds](https://github.com/microsoft/markitdown/tree/main/packages/markitdown/src/markitdown/converters): `packages/markitdown/src/markitdown/converters`
- [Images and audio](https://github.com/microsoft/markitdown/tree/main/packages/markitdown/src/markitdown/converters): `packages/markitdown/src/markitdown/converters`
- [Text and archives](https://github.com/microsoft/markitdown/tree/main/packages/markitdown/src/markitdown/converters): `packages/markitdown/src/markitdown/converters`

### Cloud analysis

- [Document Intelligence](https://github.com/microsoft/markitdown/blob/main/packages/markitdown/src/markitdown/converters/_doc_intel_converter.py): `packages/markitdown/src/markitdown/converters/_doc_intel_converter.py`
- [Content Understanding](https://github.com/microsoft/markitdown/blob/main/packages/markitdown/src/markitdown/converters/_cu_converter.py): `packages/markitdown/src/markitdown/converters/_cu_converter.py`

### OCR plugin

- [OCR registration](https://github.com/microsoft/markitdown/blob/main/packages/markitdown-ocr/src/markitdown_ocr/_plugin.py): `packages/markitdown-ocr/src/markitdown_ocr/_plugin.py`
- [PDF OCR](https://github.com/microsoft/markitdown/blob/main/packages/markitdown-ocr/src/markitdown_ocr/_pdf_converter_with_ocr.py): `packages/markitdown-ocr/src/markitdown_ocr/_pdf_converter_with_ocr.py`
- [DOCX OCR](https://github.com/microsoft/markitdown/blob/main/packages/markitdown-ocr/src/markitdown_ocr/_docx_converter_with_ocr.py): `packages/markitdown-ocr/src/markitdown_ocr/_docx_converter_with_ocr.py`
- [PPTX OCR](https://github.com/microsoft/markitdown/blob/main/packages/markitdown-ocr/src/markitdown_ocr/_pptx_converter_with_ocr.py): `packages/markitdown-ocr/src/markitdown_ocr/_pptx_converter_with_ocr.py`
- [XLSX OCR](https://github.com/microsoft/markitdown/blob/main/packages/markitdown-ocr/src/markitdown_ocr/_xlsx_converter_with_ocr.py): `packages/markitdown-ocr/src/markitdown_ocr/_xlsx_converter_with_ocr.py`
- [LLM vision OCR](https://github.com/microsoft/markitdown/blob/main/packages/markitdown-ocr/src/markitdown_ocr/_ocr_service.py): `packages/markitdown-ocr/src/markitdown_ocr/_ocr_service.py`

### User interfaces

- [Command line](https://github.com/microsoft/markitdown/blob/main/packages/markitdown/src/markitdown/__main__.py): `packages/markitdown/src/markitdown/__main__.py`
- [MCP server](https://github.com/microsoft/markitdown/blob/main/packages/markitdown-mcp/src/markitdown_mcp/__main__.py): `packages/markitdown-mcp/src/markitdown_mcp/__main__.py`

### Other components

- **Caller**
- **Azure services**
- **Vision API**

## Connections

- Caller → Command line: runs (evidence: `README.md`)
- Caller → Conversion engine: calls (evidence: `README.md`)
- Caller → MCP server: uses
- Command line → Conversion engine: invokes (evidence: `packages/markitdown/src/markitdown/__main__.py`)
- MCP server → Conversion engine: imports (evidence: `packages/markitdown-mcp/src/markitdown_mcp/__main__.py`)
- Conversion engine → Stream metadata: builds (evidence: `packages/markitdown/src/markitdown/_markitdown.py`)
- Conversion engine → Converter registry: dispatches (evidence: `packages/markitdown/src/markitdown/_markitdown.py`)
- Conversion engine → Converter contract: registers (evidence: `packages/markitdown/src/markitdown/_markitdown.py`)
- Converter registry → Office formats: exports (evidence: `packages/markitdown/src/markitdown/converters/__init__.py`)
- Converter registry → PDF conversion: exports (evidence: `packages/markitdown/src/markitdown/converters/__init__.py`)
- Converter registry → Web and feeds: exports (evidence: `packages/markitdown/src/markitdown/converters/__init__.py`)
- Converter registry → Images and audio: exports (evidence: `packages/markitdown/src/markitdown/converters/__init__.py`)
- Converter registry → Text and archives: exports (evidence: `packages/markitdown/src/markitdown/converters/__init__.py`)
- Conversion engine → Document Intelligence: registers (evidence: `README.md`)
- Conversion engine → Content Understanding: registers (evidence: `README.md`)
- Document Intelligence → Azure services: requests analysis (evidence: `README.md`)
- Content Understanding → Azure services: requests analysis (evidence: `README.md`)
- Conversion engine → OCR registration: loads optionally (evidence: `README.md`)
- OCR registration → PDF OCR: registers (evidence: `packages/markitdown-ocr/src/markitdown_ocr/_plugin.py`)
- OCR registration → DOCX OCR: registers (evidence: `packages/markitdown-ocr/src/markitdown_ocr/_plugin.py`)
- OCR registration → PPTX OCR: registers (evidence: `packages/markitdown-ocr/src/markitdown_ocr/_plugin.py`)
- OCR registration → XLSX OCR: registers (evidence: `packages/markitdown-ocr/src/markitdown_ocr/_plugin.py`)
- PDF OCR → LLM vision OCR: extracts text (evidence: `packages/markitdown-ocr/src/markitdown_ocr/_pdf_converter_with_ocr.py`)
- DOCX OCR → LLM vision OCR: extracts text (evidence: `packages/markitdown-ocr/src/markitdown_ocr/_docx_converter_with_ocr.py`)
- LLM vision OCR → Vision API: sends image (evidence: `packages/markitdown-ocr/src/markitdown_ocr/_ocr_service.py`)
- Conversion engine → Markdown result: returns Markdown (evidence: `README.md`)
- Office formats → Markdown result: produces Markdown (evidence: `README.md`)
- PDF conversion → Markdown result: produces Markdown (evidence: `README.md`)
- Web and feeds → Markdown result: produces Markdown (evidence: `README.md`)
- Images and audio → Markdown result: produces Markdown (evidence: `README.md`)
- Text and archives → Markdown result: produces Markdown (evidence: `README.md`)
