This document describes the markitdown-sample-plugin package, a reference implementation demonstrating how to create plugins for MarkItDown. The plugin extends MarkItDown with RTF (Rich Text Format) conversion capabilities using the striprtf library. This sample serves as a template for third-party developers building custom converters for additional file formats.
For information about the broader plugin architecture and interface requirements, see Creating and Registering Plugins. For general plugin system architecture, see Plugin System.
Sources: packages/markitdown-sample-plugin/README.md1-112
The sample plugin demonstrates the complete plugin lifecycle, from package structure to runtime registration. The plugin system uses Python's entry point mechanism for discovery and requires specific interface conformance for compatibility.
Sources: packages/markitdown-sample-plugin/src/markitdown_sample_plugin/_plugin.py1-72 packages/markitdown-sample-plugin/pyproject.toml1-71
The plugin exposes two required interface elements at the module level. These declarations enable MarkItDown to verify compatibility and invoke the plugin during initialization.
The __plugin_interface_version__ constant declares compatibility with the plugin API:
Location: packages/markitdown-sample-plugin/src/markitdown_sample_plugin/_plugin.py13-15
MarkItDown validates this value before loading the plugin. Currently, version 1 is the only supported interface version.
The register_converters() function serves as the plugin's entry point. MarkItDown invokes this function during instance construction when plugins are enabled:
Location: packages/markitdown-sample-plugin/src/markitdown_sample_plugin/_plugin.py25-31
The function receives the MarkItDown instance being constructed and must call markitdown.register_converter() to attach converters.
Sources: packages/markitdown-sample-plugin/src/markitdown_sample_plugin/_plugin.py13-31 packages/markitdown-sample-plugin/README.md47-62
The RtfConverter class implements the DocumentConverter interface, providing RTF-to-Markdown conversion using the striprtf library.
Sources: packages/markitdown-sample-plugin/src/markitdown_sample_plugin/_plugin.py34-72
The accepts() method determines whether the converter can handle a given file stream. It checks both MIME type and file extension:
| Check Type | Accepted Values |
|---|---|
| MIME Type Prefixes | text/rtf, application/rtf |
| File Extensions | .rtf |
Implementation: packages/markitdown-sample-plugin/src/markitdown_sample_plugin/_plugin.py39-55
The method first checks the file extension from stream_info.extension, then falls back to MIME type prefix matching from stream_info.mimetype. Both values are normalized to lowercase for case-insensitive comparison.
Sources: packages/markitdown-sample-plugin/src/markitdown_sample_plugin/_plugin.py17-55
The convert() method performs the actual RTF-to-Markdown transformation:
Location: packages/markitdown-sample-plugin/src/markitdown_sample_plugin/_plugin.py57-71
The converter:
stream_info.charset, defaulting to locale.getpreferredencoding()striprtf.rtf_to_text() for conversionDocumentConverterResult with title=None and the converted markdown textNote: The converter uses the striprtf library's plain text extraction, which strips RTF formatting codes but does not preserve semantic structure like headers or lists in Markdown format.
Sources: packages/markitdown-sample-plugin/src/markitdown_sample_plugin/_plugin.py57-72
The plugin registers itself with MarkItDown through the Python entry point system configured in pyproject.toml:
Location: packages/markitdown-sample-plugin/pyproject.toml39-41
| Configuration Element | Value | Purpose |
|---|---|---|
| Entry Point Group | markitdown.plugin | Standard group name for MarkItDown plugin discovery |
| Plugin Key | sample_plugin | Arbitrary identifier for the plugin (can be any unique string) |
| Module Path | markitdown_sample_plugin | Fully-qualified module name containing __plugin_interface_version__ and register_converters() |
MarkItDown scans all installed packages for entry points in the markitdown.plugin group when enable_plugins=True is specified.
Sources: packages/markitdown-sample-plugin/pyproject.toml39-41 packages/markitdown-sample-plugin/README.md65-72
The plugin declares two runtime dependencies in its pyproject.toml:
| Dependency | Version Constraint | Purpose |
|---|---|---|
markitdown | >=0.1.0a1 | Provides base DocumentConverter class and plugin interfaces |
striprtf | No constraint | Performs RTF-to-plain-text conversion |
Location: packages/markitdown-sample-plugin/pyproject.toml26-29
The dependency on markitdown ensures that plugin users have the core library installed. The striprtf library handles the RTF parsing and conversion logic.
Sources: packages/markitdown-sample-plugin/pyproject.toml26-29
Install the plugin package using pip from the plugin directory:
Note: The -e flag installs in editable mode, allowing development and testing without reinstallation after code changes.
Verify plugin installation using the CLI's plugin listing command:
This command displays all discovered plugins registered under the markitdown.plugin entry point group.
Enable plugins during conversion using the --use-plugins flag:
Without --use-plugins, installed plugins remain inactive.
Enable plugins programmatically by passing enable_plugins=True to the MarkItDown constructor:
Sources: packages/markitdown-sample-plugin/README.md75-103
The following diagram shows the complete lifecycle from installation to conversion, using actual code entities:
Sources: packages/markitdown-sample-plugin/src/markitdown_sample_plugin/_plugin.py1-72 packages/markitdown-sample-plugin/pyproject.toml39-41
The plugin package follows this structure:
packages/markitdown-sample-plugin/
├── pyproject.toml # Package configuration and entry point
├── README.md # Usage documentation
└── src/markitdown_sample_plugin/
├── __about__.py # Version metadata
└── _plugin.py # Plugin implementation
| File | Key Contents |
|---|---|
pyproject.toml | Entry point declaration, dependencies (markitdown, striprtf) |
_plugin.py | __plugin_interface_version__, register_converters(), RtfConverter class |
__about__.py | __version__ string |
Sources: packages/markitdown-sample-plugin/pyproject.toml1-71 packages/markitdown-sample-plugin/src/markitdown_sample_plugin/_plugin.py1-72 packages/markitdown-sample-plugin/src/markitdown_sample_plugin/__about__.py1-5
Refresh this wiki