markitdown

Files (11)

• SKILL.md
• api_reference.md · references/
• cloud_and_ocr.md · references/
• file_formats.md · references/
• mcp_and_plugins.md · references/
• migration.md · references/
• security.md · references/
• workflows.md · references/
• batch_convert.py · scripts/
• convert_literature.py · scripts/
• inspect_installation.py · scripts/

SKILL.md (first lines)

# MarkItDown

## Overview

MarkItDown is Microsoft's lightweight Python utility for turning common documents into structure-preserving Markdown. Its output is designed primarily for indexing, text analysis, search, and LLM ingestion—not high-fidelity visual reproduction.

This skill targets **MarkItDown 0.1.8**, released September 21, 2026. New code should use `result.markdown`; `result.text_content` remains only as a soft-deprecated compatibility alias.

## Choose the Right Path

| Need | Recommended path |
|---|---|
| Trusted local PDF, Office, HTML, CSV, EPUB, or ZIP | Built-in converter with `convert_local()` |
| Uploaded bytes or an already-open file | `convert_stream()` with `StreamInfo` hints |
| Remote HTTP(S) input | Validate and fetch it yourself, then call `convert_response()` |
| Scanned PDF or text inside embedded images | Official `markitdown-ocr` vision plugin, Azure Document Intelligence, or Azure Content Understanding |
| Video, structured fields, or custom multimodal extraction | Azure Content Understanding |
| Local agent integration | Official `markitdown-mcp` server over STDIO or localhost |
| Bounding boxes, page coordinates, or screenshots | Use a layout-aware parser such as LiteParse instead |
| PDF merge/split/forms/watermarks | Use a PDF manipulation library such as `pypdf` instead |

## Installation

Create an isolated environment:

```bash
uv venv --python 3.12 .venv
source .venv/bin/activate
```

Install every built-in feature:

```bash
uv pip install "markitdown[all]==0.1.8"
```

Or install only the converters required by the task:

```bash
uv pip install "markitdown[pdf,docx,pptx,xlsx]==0.1.8"
```

Available extras in 0.1.8 are:

- `pptx`, `docx`, `xlsx`, `xls`, `pdf`, and `outlook`
- `audio-transcription` and `youtube-transcription`
- `az-doc-intel` and `az-content-understanding`
- `all`

Verify the installation:

```bash
markitdown --version
python scripts/inspect_installation.py
```

The `[all]` extra does **not** install the separate `markitdown-ocr` plugin or an OpenAI-compatible client.

## Quick Start

### Command line

```bash
# Convert a trusted local file
markitdown report.pdf -o report.md

# Write Markdown to stdout
markitdown manuscript.docx > manuscript.md

# Supply type information when reading bytes from stdin
markitdown < report.pdf -x .pdf -m application/pdf -o report.md
```

Useful CLI controls:

```bash
markitdown --list-plugins
markitdown --use-plugins document.pdf -o document.md
markitdown image.bin -x .png -m image/png -o image.md
markitdown page.html --keep-data-uris -o page.md
```

`--keep-data-uris` can make output very large and may preserve embedded sensitive data. Enable it only when required.

### Python: trusted local file

Prefer the narrow local-only API when the source is a file:

```python
from pathlib import Path

from markitdown import MarkItDown

source = Path("report.pdf")
destination = Path("report.md")

converter = MarkItDown()
result = converter.convert_local(source)
destination.write_text(result.markdown, encoding="utf-8")
```

### Python: binary stream

Use a binary, seekable stream and provide metadata when the stream has no filename:

```python
from markitdown import MarkItDown, StreamInfo

converter = MarkItDown()

with open("report.pdf", "rb") as stream:
    result = converter.convert_stream(
        stream,
        stream_info=StreamInfo(
            extension=".pdf",
            mimetype="application/pdf",
            filename="report.pdf",
        ),
    )

From K-Dense-AI/scientific-agent-skills, MIT.

More from K-Dense-AI/scientific-agent-skills