Core Components

Relevant source files

• packages/markitdown/src/markitdown/_markitdown.py

Purpose and Scope

This document provides an overview of the core components that comprise the MarkItDown system. These components form the foundational layer responsible for orchestrating document conversion, managing converter registration, handling file type detection, and processing various input sources.

The core components covered include:

• The MarkItDown orchestrator class
• StreamInfo metadata handling
• Converter registry and priority system
• Exception hierarchy
• URI handling utilities
• Plugin loading system

For details on specific converters and their implementations, see Conversion System. For deployment and integration patterns, see Integration and Deployment.

Core Component Architecture

The MarkItDown system is organized around several key components that work together to convert documents to Markdown. The following diagram shows the primary components and their relationships:

Sources: packages/markitdown/src/markitdown/_markitdown.py1-784

The MarkItDown Orchestrator

The MarkItDown class serves as the main orchestrator for the conversion system. It manages the converter registry, handles various input sources (local files, streams, URIs), and coordinates file type detection.

Initialization and Configuration

The MarkItDown class is initialized with optional parameters for enabling built-in converters and plugins:

Parameter	Type	Default	Description
enable_builtins	Union[None, bool]	None (treated as True)	Enable built-in converters
enable_plugins	Union[None, bool]	None (treated as False)	Enable plugin converters
Additional kwargs	Various	-	Configuration for LLM client, Azure services, exiftool path, etc.

When built-ins are enabled via enable_builtins() packages/markitdown/src/markitdown/_markitdown.py140-230 the orchestrator:

1. Initializes service integrations (LLM client, exiftool path)
2. Registers all built-in converters with appropriate priorities
3. Optionally registers the Azure Document Intelligence converter if endpoint is provided

Conversion Entry Points

The MarkItDown class provides multiple entry points for conversion, all routing through the internal _convert() method:

Sources: packages/markitdown/src/markitdown/_markitdown.py252-536

For detailed information on the MarkItDown class methods and usage patterns, see MarkItDown Class.

Stream Information and File Detection

The StreamInfo dataclass serves as a metadata container for file streams. It stores:

• mimetype: MIME type of the content
• charset: Character encoding
• extension: File extension (with leading dot)
• filename: Full filename
• local_path: Path to local file
• url: URL or URI of the source

File Type Detection Pipeline

File type detection uses a multi-layered approach combining multiple sources of information:

Sources: packages/markitdown/src/markitdown/_markitdown.py673-772

The _get_stream_info_guesses() method packages/markitdown/src/markitdown/_markitdown.py673-772 coordinates this detection process, producing a prioritized list of StreamInfo guesses that the converter registry will attempt in order.

For more details on stream handling, see Stream Handling and File Detection.

Converter Registry and Priority System

The converter registry is a core component that manages the selection and ordering of document converters. Each converter is wrapped in a ConverterRegistration dataclass:

Sources: packages/markitdown/src/markitdown/_markitdown.py85-91

Priority Constants

Two priority constants define the ordering:

Constant	Value	Purpose
PRIORITY_SPECIFIC_FILE_FORMAT	0.0	Specific format converters (DOCX, PDF, etc.)
PRIORITY_GENERIC_FILE_FORMAT	10.0	Generic/catch-all converters (PlainText, HTML, ZIP)

Sources: packages/markitdown/src/markitdown/_markitdown.py54-59

Lower priority values are tried first, so specific converters take precedence over generic ones.

Registration and Selection Process

Sources: packages/markitdown/src/markitdown/_markitdown.py538-631

Built-in Converter Registration Order

The built-in converters are registered in a specific order within enable_builtins() packages/markitdown/src/markitdown/_markitdown.py181-226:

Order	Converter	Priority	Notes
1	PlainTextConverter	10.0	Generic, registered first
2	ZipConverter	10.0	Generic
3	HtmlConverter	10.0	Generic
4	RssConverter	0.0	Specific formats below
5	WikipediaConverter	0.0
6	YouTubeConverter	0.0
7	BingSerpConverter	0.0
8	DocxConverter	0.0
9	XlsxConverter	0.0
10	XlsConverter	0.0
11	PptxConverter	0.0
12	AudioConverter	0.0
13	ImageConverter	0.0
14	IpynbConverter	0.0
15	PdfConverter	0.0
16	OutlookMsgConverter	0.0
17	EpubConverter	0.0
18	CsvConverter	0.0
Last	DocumentIntelligenceConverter	0.0	Optional, if endpoint provided

Due to the stable sort and insertion at position 0, converters registered later effectively have higher priority within the same priority value. This means DocumentIntelligenceConverter (if registered) and CsvConverter are tried before PlainTextConverter among specific format converters.

Sources: packages/markitdown/src/markitdown/_markitdown.py181-226

Plugin Converter Registration

Plugins can register converters with custom priorities via the register_converters() function called during plugin loading packages/markitdown/src/markitdown/_markitdown.py240-247 This allows plugins to:

• Insert converters before built-ins (priority < 0.0)
• Insert between specific and generic converters (0.0 < priority < 10.0)
• Insert after generic converters (priority > 10.0)

For details on the plugin system, see Plugin System.

Exception Handling

The exception hierarchy provides structured error reporting for conversion failures. The core exceptions are:

Sources: packages/markitdown/src/markitdown/_markitdown.py46-50

The _convert() method tracks failed conversion attempts and raises appropriate exceptions:

• FileConversionException when one or more converters accepted the file but failed packages/markitdown/src/markitdown/_markitdown.py625-626
• UnsupportedFormatException when no converter accepted the file packages/markitdown/src/markitdown/_markitdown.py629-631

For complete exception documentation, see Exception Handling.

URI Handling

The URI handling utilities support multiple URI schemes:

Scheme	Handler	Description
file:	file_uri_to_path()	Convert file URIs to local paths
data:	parse_data_uri()	Parse data URIs into mimetype and bytes
http: / https:	requests library	Fetch remote content

URI Processing Flow

Sources: packages/markitdown/src/markitdown/_markitdown.py405-464

The convert_uri() method packages/markitdown/src/markitdown/_markitdown.py405-464 serves as the entry point for all URI processing, dispatching to the appropriate handler based on the scheme.

For detailed URI handling documentation, see URI Handling.

Plugin Loading System

The plugin system enables third-party extensions to register custom converters without modifying the core codebase. Plugins are discovered using Python's entry_points mechanism.

Plugin Discovery and Loading

Sources: packages/markitdown/src/markitdown/_markitdown.py65-82 packages/markitdown/src/markitdown/_markitdown.py232-250

Plugin Interface

Plugins must implement a register_converters() function with the signature:

The function receives the MarkItDown instance and any keyword arguments passed during initialization. Plugins typically:

1. Create converter instances
2. Call markitdown.register_converter() with appropriate priorities
3. Handle initialization errors gracefully

For a complete example and detailed plugin documentation, see Plugin System and Sample RTF Converter Plugin.

Normalization and Post-Processing

After successful conversion, the _convert() method normalizes the output Markdown packages/markitdown/src/markitdown/_markitdown.py617-622:

1. Line ending normalization: Splits on \r?\n and removes trailing whitespace from each line
2. Excessive blank line reduction: Replaces 3+ consecutive newlines with exactly 2 newlines

This ensures consistent Markdown formatting regardless of the source document's line endings or spacing.

Sources: packages/markitdown/src/markitdown/_markitdown.py617-622

Summary

The core components work together to provide a flexible, extensible document conversion system:

• MarkItDown orchestrator coordinates the conversion process
• StreamInfo carries file metadata through the pipeline
• Converter registry with priority system selects appropriate converters
• File detection uses ML and heuristics for robust type identification
• Exception hierarchy provides structured error reporting
• URI handling supports multiple input schemes
• Plugin system enables third-party extensions

These components form the foundation upon which all document converters are built. For information on specific converters, see Conversion System.