Plugin Development

Create and distribute MarkItDown plugins to share custom converters

Plugins allow you to package and distribute custom converters as standalone Python packages. MarkItDown automatically discovers and loads plugins using Python’s entry points system.

Plugin Architecture

MarkItDown uses the markitdown.plugin entry point group to discover plugins. When enable_plugins=True, MarkItDown calls each plugin’s register_converters() function during initialization.

Plugins are disabled by default. Users must explicitly enable them with enable_plugins=True or the --use-plugins CLI flag.

Creating a Plugin

Complete Example: RTF Plugin

Here’s the complete RTF converter plugin from packages/markitdown-sample-plugin/:

import locale
from typing import BinaryIO, Any
from striprtf.striprtf import rtf_to_text

from markitdown import (
    MarkItDown,
    DocumentConverter,
    DocumentConverterResult,
    StreamInfo,
)

__plugin_interface_version__ = 1

ACCEPTED_MIME_TYPE_PREFIXES = [
    "text/rtf",
    "application/rtf",
]

ACCEPTED_FILE_EXTENSIONS = [".rtf"]

def register_converters(markitdown: MarkItDown, **kwargs):
    """
    Called during construction of MarkItDown instances.
    """
    markitdown.register_converter(RtfConverter())

class RtfConverter(DocumentConverter):
    """Converts RTF 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 extension in ACCEPTED_FILE_EXTENSIONS:
            return True
        
        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:
        # Read the file using the charset or system default
        encoding = stream_info.charset or locale.getpreferredencoding()
        stream_data = file_stream.read().decode(encoding)
        
        # Convert and return
        return DocumentConverterResult(
            title=None,
            markdown=rtf_to_text(stream_data),
        )

Installing and Testing Your Plugin

Writing Plugin Tests

Create tests to verify both direct converter usage and plugin loading:

import os
from markitdown import MarkItDown, StreamInfo
from markitdown_sample_plugin import RtfConverter

TEST_FILES_DIR = os.path.join(os.path.dirname(__file__), "test_files")

def test_converter():
    """Test the converter directly."""
    with open(os.path.join(TEST_FILES_DIR, "test.rtf"), "rb") as file_stream:
        converter = RtfConverter()
        result = converter.convert(
            file_stream=file_stream,
            stream_info=StreamInfo(
                mimetype="text/rtf",
                extension=".rtf",
                filename="test.rtf"
            ),
        )
        
        assert "Expected content" in result.markdown

def test_markitdown():
    """Test that MarkItDown loads the plugin correctly."""
    md = MarkItDown(enable_plugins=True)
    result = md.convert(os.path.join(TEST_FILES_DIR, "test.rtf"))
    
    assert "Expected content" in result.markdown

Plugin Loading Process

MarkItDown loads plugins using this process (_markitdown.py:65):

1. When enable_plugins=True, MarkItDown calls enable_plugins() method
2. _load_plugins() discovers all markitdown.plugin entry points
3. Each entry point is loaded and its register_converters() function is called
4. If any plugin fails to load, a warning is issued and the plugin is skipped

def _load_plugins() -> List[Any]:
    """Lazy load plugins."""
    plugins = []
    for entry_point in entry_points(group="markitdown.plugin"):
        try:
            plugins.append(entry_point.load())
        except Exception:
            warn(f"Plugin '{entry_point.name}' failed to load")
    return plugins

Best Practices

Version Compatibility: Always set __plugin_interface_version__ = 1 and specify minimum MarkItDown version in dependencies.

Graceful Degradation: Handle import errors for optional dependencies and provide helpful error messages.

Priority Configuration: Allow users to pass priority via **kwargs in register_converters():

def register_converters(markitdown: MarkItDown, **kwargs):
    priority = kwargs.get("my_converter_priority", 0.0)
    markitdown.register_converter(MyConverter(), priority=priority)

Documentation: Include clear README with installation instructions and example usage.

Publishing Your Plugin

To share your plugin with others:

1. Naming Convention: Use markitdown-<name>-plugin for package name
2. PyPI Publishing: Follow standard Python package publishing process
3. Documentation: Include clear installation and usage instructions
4. Testing: Ensure comprehensive test coverage

# Build the package
python -m build

# Upload to PyPI
python -m twine upload dist/*

Users can then install your plugin:

pip install markitdown-sample-plugin

Next Steps

Custom Converters

Learn more about implementing converters

Configuration

Understand MarkItDown configuration options