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/migration.md
View on GitHub# Migration and Release Notes
This skill targets MarkItDown 0.1.8. The timeline below summarizes changes that affect user code and operational guidance.
## Release Timeline
### 0.1.0 — March 22, 2025
Major architecture release:
- Optional dependency feature groups introduced
- Plugin architecture introduced
- Conversions moved to in-memory streams; temporary files removed
- EPUB support added
- CLI extension, MIME, and charset hints added
- `--keep-data-uris` added
Breaking changes:
- Install `[all]` for behavior comparable to earlier all-in-one installs.
- `convert_stream()` now requires a binary stream.
- `DocumentConverter` implementations now receive binary streams plus `StreamInfo`, not file paths.
### 0.1.1 — March 25, 2025
- `convert_url()` renamed to `convert_uri()`.
- `file:` and `data:` URI handling added.
- `convert_url()` retained as a compatibility alias.
### 0.1.2 — May 28, 2025
- DOCX math-equation rendering
- Dedicated CSV-to-Markdown conversion
- XML/OMML parsing switched to `defusedxml`
- Document Intelligence credential/API-version improvements
- Streamable HTTP MCP support
- YouTube transcript fixes
- Python requirement updated to 3.10+
### 0.1.3 — August 26, 2025
- Safer ExifTool handling, requiring version 12.24 or later
- MCP plugin enablement through `MARKITDOWN_ENABLE_PLUGINS`
- DOCX linked-image fixes
- Document Intelligence HTML type handling
- Custom LLM prompt forwarding fix
- Additional HTML/PPTX robustness
### 0.1.4 — December 1, 2025
Security maintenance release:
- Mammoth updated to address CVE-2025-11849
- `pdfminer.six` updated to address GHSA-wf5f-4jwr-ppcp
### 0.1.5 — February 20, 2026
- Better aligned and wide PDF tables
- Partially numbered PDF-list fix
- `text/markdown` added to the HTTP Accept header
- Windows ONNX Runtime pin removed
### 0.1.6 — May 26, 2026
- Official OCR layer/plugin for embedded images and scanned PDFs
- PDF page cleanup to fix linear memory growth
- Deeply nested HTML recursion fix
- Azure Content Understanding converter
- Expanded security guidance for broad I/O and MCP binding
### 0.1.7 and 0.1.8 — maintenance through September 21, 2026
- Python supports >=3.10,<3.15.
- Document Intelligence defers API version selection to its SDK instead of hardcoding the old preview.
- CU uses the SDK `to_llm_input()` helper and requires `azure-ai-contentunderstanding>=1.2.0b1`; see the preview-default caveat in `cloud_and_ocr.md`.
- CLI cloud endpoints can come from `MARKITDOWN_DOCINTEL_ENDPOINT` and `MARKITDOWN_CU_ENDPOINT`; stdin is buffered before detection.
- CSV preserves wider rows and CR-only lines; notebook BOM/headings, RSS/Atom links/content, and duplicate ZIP member handling improved.
- `markitdown-ocr==0.1.1` uses core Office image hooks and needs core >=0.1.8.
- `markitdown-mcp==0.0.1a7` uses MCP SDK 2.x.
- URI schemes are case-insensitive; `file:` rejects UNC/device paths. Local path authorization is still the caller's responsibility.
## Upgrade Installation
Create a clean environment for the comparison:
```bash
uv venv --python 3.12 .venv-markitdown
source .venv-markitdown/bin/activate
uv pip install "markitdown[all]==0.1.8"
```
Do not test a migration in an environment that still contains unknown third-party plugins.
## Code Replacements
### Result content
Old/compatibility:
```python
content = result.text_content
```
Current:
```python
content = result.markdown
```
`text_content` still works in 0.1.8 but is explicitly documented in source as a soft-deprecated alias.
### Local conversion
Broad:
```python
result = converter.convert(user_value)
```
Narrow local path:
```python
result = converter.convert_local(validated_path)
```
Use `convert_stream()` for validated uploaded bytes and `convert_response()` after an application-controlled download.
### Streams
Old:
```python
from io import StringIO
result = converter.convert_stream(StringIO("text"))
```
Current:
```python
from io import BytesIO
from markitdown import StreamInfo
result = converter.convert_stream(
BytesIO(b"text"),
stream_info=StreamInfo(
extension=".txt",
mimetype="text/plain",
charset="utf-8",
),
)
```
### URI API
Old:
```python
result = converter.convert_url(uri)
```
Current:
```python
result = converter.convert_uri(validated_uri)
```
Prefer caller-controlled fetching plus `convert_response()` for HTTP(S).
### Hints
Legacy:
```python
result = converter.convert_stream(stream, file_extension=".pdf")
```
Current:
```python
from markitdown import StreamInfo
result = converter.convert_stream(
stream,
stream_info=StreamInfo(
extension=".pdf",
mimetype="application/pdf",
filename="upload.pdf",
),
)
```
The legacy `file_extension`/`url` parameters still exist but are marked for migration in source.
## Custom Converter Migration
Pre-0.1 converter:
```python
class OldConverter(DocumentConverter):
def convert(self, file_path):
...
```
0.1.x converter:
```python
from typing import Any, BinaryIO
from markitdown import DocumentConverter, DocumentConverterResult, StreamInfo
class CurrentConverter(DocumentConverter):
def accepts(
self,
file_stream: BinaryIO,
stream_info: StreamInfo,
**kwargs: Any,
) -> bool:
...
def convert(
self,
file_stream: BinaryIO,
stream_info: StreamInfo,
**kwargs: Any,
) -> DocumentConverterResult:
return DocumentConverterResult(markdown="...")
```
If `accepts()` peeks at bytes, restore the original stream position before returning.
## Plugin Packaging Migration
Outdated entry-point group:
```toml
[project.entry-points."markitdown.plugins"]
```
Current group:
```toml
[project.entry-points."markitdown.plugin"]
example = "example_markitdown_plugin"
```
The plugin module must export:
```python
__plugin_interface_version__ = 1
def register_converters(markitdown, **kwargs):
...
```
Use `pyproject.toml`; old `setup.py`-only examples are no longer the preferred packaging pattern.
## Installation Guidance Migration
Outdated:
```bash
uv pip install markitdown
uv pip install "markitdown[all]"
```
Repository-standard reproducible install:
```bash
uv pip install "markitdown[all]==0.1.8"
```
The base package no longer implies every format dependency. Select an extra or `[all]`.
## OCR Guidance Migration
Remove these stale claims:
- "Built-in PDF conversion uses Tesseract"
- "All images are OCR'd locally"
- "GIF and WebP are handled by the built-in image converter"
Current behavior:
- Built-in PDF extracts an existing text layer.
- Built-in JPEG/PNG conversion extracts metadata and optionally requests an LLM description.
- `markitdown-ocr==0.1.1` uses an external vision-capable client for embedded images and scanned-PDF page fallback.
- Azure Document Intelligence and Content Understanding provide cloud OCR/extraction.
The official OCR plugin README's `--llm-client`/`--llm-model` CLI example is not accepted by the 0.1.8 core CLI parser. Configure the plugin in Python.
## Azure Migration
Current constructors accept explicit credentials:
```python
MarkItDown(
docintel_endpoint="https://...",
docintel_credential=credential,
)
MarkItDown(
cu_endpoint="https://...",
cu_credential=credential,
)
```
Without an explicit credential, the 0.1.8 converters use the named `AZURE_API_KEY` if present and otherwise `DefaultAzureCredential`.
Do not rely on undocumented variable names such as `AZURE_DOCUMENT_INTELLIGENCE_KEY` for these constructors.
Content Understanding is new in 0.1.6:
```python
from markitdown import MarkItDown
converter = MarkItDown(
cu_endpoint="https://...",
cu_analyzer_id="optional-custom-analyzer",
)
```
## Security Migration
Replace:
- User-controlled `convert(value)` calls
- Broad URI access
- Automatic plugin enablement
- Undisclosed LLM/cloud fallback
- Secrets embedded in examples
- MCP binding to non-local interfaces
With:
- Narrow conversion APIs
- Path and destination allowlists
- Explicit size/time/resource limits
- Reviewed, pinned, opt-in plugins
- User-approved external processing
- Named credentials through secure provider configuration
- STDIO or localhost-only MCP in a sandbox
## Regression Checklist
- [ ] Install 0.1.8 in a clean environment
- [ ] Replace `.text_content` with `.markdown`
- [ ] Replace text streams with binary streams
- [ ] Replace `convert_url()` with `convert_uri()` or controlled fetch
- [ ] Update custom converter signatures
- [ ] Update plugin entry-point group
- [ ] Pin format extras
- [ ] Test PDF tables and multi-column reading order
- [ ] Test DOCX math and linked images
- [ ] Test PPTX grouped shapes and notes
- [ ] Confirm plugins remain disabled by default
- [ ] Confirm no conversion unexpectedly calls network/cloud
- [ ] Compare semantic output on a representative corpus
## Sources
- Releases: https://github.com/microsoft/markitdown/releases
- 0.1.0 migration notes: https://github.com/microsoft/markitdown/releases/tag/v0.1.0
- 0.1.6 release: https://github.com/microsoft/markitdown/releases/tag/v0.1.6
- 0.1.8 release: https://github.com/microsoft/markitdown/releases/tag/v0.1.8
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 |