Custom Converters

Create custom document converters to extend MarkItDown’s file format support

Custom converters allow you to extend MarkItDown to support additional file formats. By implementing the DocumentConverter base class, you can add conversion logic for any file type.

DocumentConverter Base Class

All converters inherit from the DocumentConverter abstract base class located in _base_converter.py:42.

from markitdown import DocumentConverter, DocumentConverterResult, StreamInfo
from typing import BinaryIO, Any

class DocumentConverter:
    """Abstract superclass of all DocumentConverters."""
    
    def accepts(self, file_stream: BinaryIO, stream_info: StreamInfo, **kwargs: Any) -> bool:
        """Determine if this converter can handle the document."""
        raise NotImplementedError()
    
    def convert(self, file_stream: BinaryIO, stream_info: StreamInfo, **kwargs: Any) -> DocumentConverterResult:
        """Convert the document to Markdown."""
        raise NotImplementedError()

Creating a Custom Converter

Complete Example

Here’s a complete example based on the plain text converter (converters/_plain_text_converter.py:33):

from typing import BinaryIO, Any
from charset_normalizer import from_bytes
from markitdown import (
    DocumentConverter,
    DocumentConverterResult,
    StreamInfo
)

ACCEPTED_MIME_TYPE_PREFIXES = [
    "text/",
    "application/json",
    "application/markdown",
]

ACCEPTED_FILE_EXTENSIONS = [
    ".txt",
    ".text",
    ".md",
    ".markdown",
    ".json",
    ".jsonl",
]

class PlainTextConverter(DocumentConverter):
    """Converts plain text files to Markdown."""
    
    def accepts(
        self,
        file_stream: BinaryIO,
        stream_info: StreamInfo,
        **kwargs: Any,
    ) -> bool:
        mimetype = (stream_info.mimetype or "").lower()
        extension = (stream_info.extension or "").lower()
        
        # If we have a charset, safely assume it's text
        if stream_info.charset is not None:
            return True
        
        # Check extension
        if extension in ACCEPTED_FILE_EXTENSIONS:
            return True
        
        # Check mimetype prefix
        for prefix in ACCEPTED_MIME_TYPE_PREFIXES:
            if mimetype.startswith(prefix):
                return True
        
        return False
    
    def convert(
        self,
        file_stream: BinaryIO,
        stream_info: StreamInfo,
        **kwargs: Any,
    ) -> DocumentConverterResult:
        if stream_info.charset:
            text_content = file_stream.read().decode(stream_info.charset)
        else:
            text_content = str(from_bytes(file_stream.read()).best())
        
        return DocumentConverterResult(markdown=text_content)

StreamInfo Object

The StreamInfo dataclass (_stream_info.py:6) provides metadata about the file being converted:

@dataclass(kw_only=True, frozen=True)
class StreamInfo:
    mimetype: Optional[str] = None      # MIME type (e.g., "application/pdf")
    extension: Optional[str] = None     # File extension (e.g., ".pdf")
    charset: Optional[str] = None       # Character encoding (e.g., "utf-8")
    filename: Optional[str] = None      # Filename from path or URL
    local_path: Optional[str] = None    # Full local file path
    url: Optional[str] = None           # URL if fetched from web

DocumentConverterResult

The DocumentConverterResult class (_base_converter.py:5) wraps the conversion output:

result = DocumentConverterResult(
    markdown="# Converted Content\n\nThis is the converted text.",
    title="Optional Document Title"
)

# Access the markdown
print(result.markdown)
print(str(result))  # Same as markdown

# Access the title
print(result.title)

Converter Priority

When registering converters, you can specify priority to control the order they’re tried:

from markitdown import MarkItDown

md = MarkItDown()

# Higher priority (tried first)
md.register_converter(SpecificConverter(), priority=0.0)

# Lower priority (tried later)
md.register_converter(GenericConverter(), priority=10.0)

Priority values (_markitdown.py:54):

• 0.0 - PRIORITY_SPECIFIC_FILE_FORMAT (specific converters like PDF, DOCX)
• 10.0 - PRIORITY_GENERIC_FILE_FORMAT (generic converters like HTML, plain text)

Lower values are tried first. Converters with the same priority maintain registration order (most recent first).

Best Practices

Stream Position Management: Always reset file_stream position after reading in accepts(). The convert() method expects the stream to be at the original position.

Charset Detection: Use stream_info.charset when available, or employ libraries like charset_normalizer to detect encoding automatically.

Dependency Handling: For optional dependencies, catch import errors gracefully and raise MissingDependencyException during conversion if needed.

Next Steps

Plugin Development

Package your converter as a reusable plugin

Configuration

Learn about MarkItDown configuration options