Markitdown

# MarkItDown Advanced Features

Advanced functionality for custom converters, URI handling, and plugins.

## Conversion Methods

MarkItDown provides multiple conversion entry points.

### convert()

Universal method that auto-detects source type.

```python
from markitdown import MarkItDown

md = MarkItDown()

# File path
result = md.convert("document.pdf")

# URL
result = md.convert("https://example.com/page.html")

# HTTP Response object
import requests
response = requests.get("https://example.com/doc.pdf")
result = md.convert(response)
```

### convert_local()

For local file paths only.

```python
from markitdown import MarkItDown

md = MarkItDown()
result = md.convert_local("./documents/report.pdf")
print(result.text_content)
```

### convert_stream()

For binary file-like objects.

```python
from markitdown import MarkItDown
import io

md = MarkItDown()

# From bytes
with open("document.pdf", "rb") as f:
    content = f.read()

stream = io.BytesIO(content)
result = md.convert_stream(stream)

# From HTTP response
import requests
response = requests.get("https://example.com/doc.pdf")
stream = io.BytesIO(response.content)
result = md.convert_stream(stream)
```

> **Note:** `convert_stream()` requires binary streams only (v0.1.0+).
> Text streams (`io.StringIO`) are not supported.

### convert_url()

For HTTP/HTTPS URLs.

```python
from markitdown import MarkItDown

md = MarkItDown()
result = md.convert_url("https://example.com/document.pdf")
print(result.text_content)
```

### convert_uri()

For any URI scheme (http, https, file, data).

```python
from markitdown import MarkItDown

md = MarkItDown()

# HTTP URL
result = md.convert_uri("https://example.com/page.html")

# Local file URI
result = md.convert_uri("file:///path/to/document.pdf")

# Data URI
result = md.convert_uri("data:text/plain;base64,SGVsbG8gV29ybGQ=")
```

### convert_response()

For `requests.Response` objects.

```python
from markitdown import MarkItDown
import requests

md = MarkItDown()
response = requests.get("https://example.com/report.pdf")
result = md.convert_response(response)
print(result.text_content)
```

## Result Object

The `DocumentConverterResult` contains conversion output.

```python
from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("document.pdf")

# Main content
print(result.text_content)

# Alias for text_content
print(result.markdown)

# Document title (if available)
if result.title:
    print(f"Title: {result.title}")
```

## Custom Converters

Create custom converters for unsupported formats.

### Basic Custom Converter

```python
from markitdown import MarkItDown
from markitdown._base_converter import DocumentConverter
from markitdown._base_converter import DocumentConverterResult
from typing import BinaryIO

class MyFormatConverter(DocumentConverter):
    """Converter for .myformat files."""

    def accepts(
        self,
        file_stream: BinaryIO,
        stream_info: "StreamInfo",
        **kwargs
    ) -> bool:
        """Check if this converter handles the file."""
        # Check by extension
        if stream_info.extension:
            return stream_info.extension.lower() == ".myformat"
        # Check by MIME type
        if stream_info.mime_type:
            return stream_info.mime_type == "application/x-myformat"
        return False

    def convert(
        self,
        file_stream: BinaryIO,
        stream_info: "StreamInfo",
        **kwargs
    ) -> DocumentConverterResult:
        """Convert the file to markdown."""
        content = file_stream.read().decode("utf-8")

        # Process content...
        markdown = f"# My Format\n\n{content}"

        return DocumentConverterResult(
            title="My Document",
            text_content=markdown
        )

# Register the converter
md = MarkItDown()
md.register_converter(MyFormatConverter())

# Use it
result = md.convert("document.myformat")
```

### Converter Priority

Converters are matched in priority order (lower = higher priority