K-Dense-AI/scientific-agent-skills / skills/markitdown
markitdown
VerifiedConverts heterogeneous documents and selected URIs to Markdown with Microsoft MarkItDown for text analysis, search, and LLM/RAG ingestion. Covers safe local conversion, streams, Office/PDF/data formats, batch workflows, plugins, vision OCR, Azure extraction, and the official MCP server.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.9 KB |
| references/api_reference.md | markdown | 11.6 KB |
| references/cloud_and_ocr.md | markdown | 13.8 KB |
| references/file_formats.md | markdown | 11.5 KB |
| references/mcp_and_plugins.md | markdown | 7.1 KB |
| references/migration.md | markdown | 9.0 KB |
| references/security.md | markdown | 10.2 KB |
| references/workflows.md | markdown | 8.0 KB |
| scripts/batch_convert.py | script | 10.3 KB |
| scripts/convert_literature.py | script | 11.8 KB |
| scripts/inspect_installation.py | script | 4.8 KB |
references/api_reference.md
View on GitHub# MarkItDown 0.1.8 API Reference
Verified against the `v0.1.8` source tag and installed package on October 1, 2026.
## Public Imports
```python
from markitdown import (
DocumentConverter,
DocumentConverterResult,
FileConversionException,
MarkItDown,
MissingDependencyException,
PRIORITY_GENERIC_FILE_FORMAT,
PRIORITY_SPECIFIC_FILE_FORMAT,
StreamInfo,
UnsupportedFormatException,
)
```
Azure file-type enums are exported from `markitdown.converters`:
```python
from markitdown.converters import (
ContentUnderstandingFileType,
DocumentIntelligenceFileType,
)
```
## `MarkItDown`
### Constructor
```python
MarkItDown(
*,
enable_builtins: bool | None = None,
enable_plugins: bool | None = None,
**kwargs,
)
```
Built-in converters are enabled by default. Third-party plugins are disabled by default.
Recognized constructor keywords include:
| Keyword | Purpose |
|---|---|
| `requests_session` | Custom `requests.Session` used by HTTP(S) URI conversion |
| `llm_client` | OpenAI-compatible client for image descriptions and compatible plugins |
| `llm_model` | Provider-specific model identifier |
| `llm_prompt` | Prompt for image description/OCR |
| `exiftool_path` | Explicit trusted ExifTool executable |
| `style_map` | Mammoth style map for DOCX conversion |
| `docintel_endpoint` | Enable Azure Document Intelligence |
| `docintel_credential` | Explicit `AzureKeyCredential` or token credential |
| `docintel_file_types` | Restrict Document Intelligence routing |
| `docintel_api_version` | Azure Document Intelligence API version |
| `cu_endpoint` | Enable Azure Content Understanding |
| `cu_credential` | Explicit `AzureKeyCredential` or token credential |
| `cu_analyzer_id` | Custom Content Understanding analyzer |
| `cu_file_types` | Restrict Content Understanding routing |
The public signature uses `**kwargs`; spell these names exactly. Unknown names can be silently ignored: there is no `cu_api_version` option. `docintel_api_version=None` delegates to the installed Azure SDK default. See `cloud_and_ocr.md` for the tested SDK versions and network contracts.
### Conversion methods
#### `convert()`
```python
convert(
source: str | Path | requests.Response | BinaryIO,
*,
stream_info: StreamInfo | None = None,
**kwargs,
) -> DocumentConverterResult
```
Dispatch rules:
- `str` with a parsed `http:`, `https:`, `file:`, or `data:` scheme (case-insensitive) → `convert_uri()`
- other `str` or `Path` → `convert_local()`
- `requests.Response` → `convert_response()`
- binary file-like object → `convert_stream()`
- text stream → `TypeError`
This convenience method is broad. Prefer a narrower method for untrusted or application-facing inputs.
#### `convert_local()`
```python
convert_local(
path: str | Path,
*,
stream_info: StreamInfo | None = None,
file_extension: str | None = None,
url: str | None = None,
**kwargs,
) -> DocumentConverterResult
```
`file_extension` and `url` are legacy parameters; put overrides in `StreamInfo`.
```python
from pathlib import Path
from markitdown import MarkItDown
source = Path("experiment.xlsx")
result = MarkItDown().convert_local(source)
Path("experiment.md").write_text(result.markdown, encoding="utf-8")
```
#### `convert_stream()`
```python
convert_stream(
stream: BinaryIO,
*,
stream_info: StreamInfo | None = None,
file_extension: str | None = None,
url: str | None = None,
**kwargs,
) -> DocumentConverterResult
```
Requirements and behavior:
- The stream must be binary.
- A seekable stream is preferred.
- A non-seekable stream is copied completely into an in-memory `BytesIO`.
- `file_extension` and `url` are legacy hints; prefer `StreamInfo`.
```python
from io import BytesIO
from markitdown import MarkItDown, StreamInfo
payload = b"sample,value\ncontrol,1\ntreated,2\n"
result = MarkItDown().convert_stream(
BytesIO(payload),
stream_info=StreamInfo(
extension=".csv",
mimetype="text/csv",
charset="utf-8",
filename="results.csv",
),
)
print(result.markdown)
```
#### `convert_uri()`
```python
convert_uri(
uri: str,
*,
stream_info: StreamInfo | None = None,
file_extension: str | None = None,
mock_url: str | None = None,
**kwargs,
) -> DocumentConverterResult
```
Supported schemes:
- `file:` with an empty authority or `localhost`
- `data:`
- `http:`
- `https:`
HTTP(S) conversion uses the configured `requests.Session`, follows Requests defaults, and then buffers the complete response in memory. It does not provide an application-level SSRF policy, download-size limit, or redirect allowlist. Validate and fetch remote resources yourself before calling `convert_response()`.
`convert_url()` remains a backward-compatible alias, but new code should use `convert_uri()`.
#### `convert_response()`
```python
convert_response(
response: requests.Response,
*,
stream_info: StreamInfo | None = None,
file_extension: str | None = None,
url: str | None = None,
**kwargs,
) -> DocumentConverterResult
```
The method derives hints from `Content-Type`, `Content-Disposition`, and the response URL, then buffers every response chunk into memory. The caller is responsible for destination validation, redirect handling, timeout, maximum size, authentication, and TLS policy.
## `StreamInfo`
```python
StreamInfo(
*,
mimetype: str | None = None,
extension: str | None = None,
charset: str | None = None,
filename: str | None = None,
local_path: str | None = None,
url: str | None = None,
)
```
Examples:
```python
pdf_info = StreamInfo(
mimetype="application/pdf",
extension=".pdf",
filename="paper.pdf",
)
html_info = StreamInfo(
mimetype="text/html",
extension=".html",
charset="utf-8",
filename="article.html",
)
```
Hints are merged with extension, HTTP header, and Magika content-detection guesses. If a caller-supplied hint conflicts with content detection, MarkItDown may try both guesses.
## `DocumentConverterResult`
```python
DocumentConverterResult(
markdown: str,
*,
title: str | None = None,
)
```
Attributes and conversions:
| Interface | Status |
|---|---|
| `result.markdown` | Canonical converted Markdown |
| `result.title` | Optional source-derived title |
| `result.text_content` | Soft-deprecated alias for `markdown` |
| `str(result)` | Returns `markdown` |
```python
result = MarkItDown().convert_local("paper.pdf")
markdown = result.markdown
title = result.title
```
## Per-conversion Options
Converter-specific values can be forwarded through a conversion call:
```python
result = converter.convert_local(
"page.html",
keep_data_uris=False,
)
```
Common options:
| Option | Used by |
|---|---|
| `keep_data_uris` | HTML/Markdown conversion; preserve rather than truncate data URIs |
| `youtube_transcript_languages` | YouTube transcript language preference |
| `llm_client`, `llm_model`, `llm_prompt` | Image/PPTX description and compatible plugins |
| `style_map` | DOCX conversion |
| `exiftool_path` | Image/audio metadata |
## Exceptions
```python
from markitdown import (
FileConversionException,
MissingDependencyException,
UnsupportedFormatException,
)
```
| Exception | Meaning |
|---|---|
| `MissingDependencyException` | The converter matched, but its optional dependency is unavailable |
| `UnsupportedFormatException` | No registered converter accepted the source |
| `FileConversionException` | One or more matching converters attempted and failed |
| `TypeError` | `convert()` received an unsupported source type, such as a text stream |
```python
from markitdown import (
FileConversionException,
MarkItDown,
MissingDependencyException,
UnsupportedFormatException,
)
try:
result = MarkItDown().convert_local("input.pdf")
except MissingDependencyException:
print("Install markitdown[pdf]==0.1.8")
except UnsupportedFormatException:
print("No converter accepted this input")
except FileConversionException as exc:
print(f"A matching converter failed: {exc}")
```
## Converter Registration
```python
register_converter(
converter: DocumentConverter,
*,
priority: float = PRIORITY_SPECIFIC_FILE_FORMAT,
) -> None
```
Lower numeric priorities run first. The built-in specific-format priority is `0.0`; generic converters use `10.0`. For registrations with equal priority, the most recently registered converter is attempted first.
`register_page_converter()` is deprecated.
## Custom Converter
Version 0.1.x converters operate on binary streams and implement both `accepts()` and `convert()`:
```python
from typing import Any, BinaryIO
from markitdown import (
DocumentConverter,
DocumentConverterResult,
StreamInfo,
)
class RtfConverter(DocumentConverter):
def accepts(
self,
file_stream: BinaryIO,
stream_info: StreamInfo,
**kwargs: Any,
) -> bool:
return (stream_info.extension or "").lower() == ".rtf"
def convert(
self,
file_stream: BinaryIO,
stream_info: StreamInfo,
**kwargs: Any,
) -> DocumentConverterResult:
raw = file_stream.read()
# Replace this placeholder with a real, bounded RTF parser.
return DocumentConverterResult(
markdown=f"```text\n{raw.decode('utf-8', errors='replace')}\n```"
)
```
Do not advance the stream in `accepts()`. If inspection is necessary, save the position with `tell()` and restore it with `seek()`.
## Plugin Package Contract
The plugin module exports interface version 1 and a registration function:
```python
from markitdown import MarkItDown
__plugin_interface_version__ = 1
def register_converters(markitdown: MarkItDown, **kwargs) -> None:
markitdown.register_converter(RtfConverter())
```
Register the module through `pyproject.toml`:
```toml
[project.entry-points."markitdown.plugin"]
example = "example_markitdown_plugin"
```
Inspect and install a trusted, pinned plugin, then verify discovery:
```bash
markitdown --list-plugins
markitdown --use-plugins input.rtf -o output.md
```
## CLI Reference
```text
markitdown [options] [filename]
```
If `filename` is omitted, MarkItDown buffers all binary stdin in memory before detection. Document Intelligence mode requires a filename; CU accepts hinted stdin.
| Option | Meaning |
|---|---|
| `-v`, `--version` | Print package version |
| `-o`, `--output PATH` | Write UTF-8 Markdown to a file |
| `-x`, `--extension EXT` | File-extension hint |
| `-m`, `--mime-type TYPE` | MIME-type hint |
| `-c`, `--charset NAME` | Charset hint |
| `-d`, `--use-docintel` | Use Azure Document Intelligence |
| `-e`, `--endpoint URL` | Document Intelligence endpoint; fallback `MARKITDOWN_DOCINTEL_ENDPOINT` |
| `--use-cu`, `--use-content-understanding` | Use Azure Content Understanding |
| `--cu-endpoint URL` | Content Understanding endpoint; fallback `MARKITDOWN_CU_ENDPOINT` |
| `--cu-analyzer ID` | Custom analyzer ID |
| `--cu-file-types LIST` | Comma-separated CU file types |
| `-p`, `--use-plugins` | Enable installed third-party plugins |
| `--list-plugins` | List discovered plugins and exit |
| `--keep-data-uris` | Preserve full data URIs |
Document Intelligence and Content Understanding are mutually exclusive in one CLI invocation.
The core 0.1.8 parser does **not** expose `--llm-client` or `--llm-model`. Configure image descriptions or the OCR plugin through Python.
## Source Basis
- v0.1.8 package API: https://github.com/microsoft/markitdown/tree/v0.1.8/packages/markitdown/src/markitdown
- v0.1.8 CLI: https://github.com/microsoft/markitdown/blob/v0.1.8/packages/markitdown/src/markitdown/__main__.py
- v0.1.8 sample plugin: https://github.com/microsoft/markitdown/tree/v0.1.8/packages/markitdown-sample-plugin
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |