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/file_formats.md
View on GitHub# File Formats and Conversion Behavior
This reference targets Microsoft MarkItDown 0.1.8. "Built-in" means the converter ships in the `markitdown` package; some built-ins still require an optional dependency extra.
## Installation by Format
```bash
# Full built-in feature set
uv pip install "markitdown[all]==0.1.8"
# Common document subset
uv pip install "markitdown[pdf,docx,pptx,xlsx]==0.1.8"
# Minimal package; suitable for core text/HTML/CSV/ZIP/EPUB/IPYNB paths
uv pip install "markitdown==0.1.8"
```
## Built-in Converter Matrix
| Input | Typical extensions/source | Extra | Main behavior | Important limitations/network |
|---|---|---|---|---|
| Plain text | `.txt`, `.md`, recognized text, JSON/XML text | Core | Decodes text while preserving content | JSON/XML are not guaranteed to be normalized or pretty-printed |
| CSV | `.csv`, `text/csv` | Core | Dedicated CSV-to-Markdown table conversion | Very wide/large tables can create large Markdown |
| HTML | `.html`, `.htm` | Core | Headings, links, lists, tables, and readable text | CSS layout, client-side rendering, and visual fidelity are not preserved |
| RSS/Atom-like XML | feed content/URLs | Core | Feed-focused Markdown | Remote retrieval uses network if a URI is supplied |
| Wikipedia page | Wikipedia URL | Core | Page-oriented Markdown | Network; URL-specific converter |
| Bing result page | Bing search-result URL | Core | Search-result-oriented Markdown | Network; HTML and service behavior can change |
| YouTube | watch, `youtu.be`, shorts or embed URLs | `youtube-transcription` for transcript | Metadata, description, and available transcript | Fetches YouTube page/transcript; captions may be absent or restricted |
| ZIP | `.zip` | Core | Iterates members and invokes nested converters | Treat untrusted archives as hostile; output can expand substantially |
| EPUB | `.epub` | Core | Book metadata and structured text | Complex styling, fixed layout, DRM, and interactive content are not preserved |
| Jupyter Notebook | `.ipynb` | Core | Notebook cells and content to Markdown | Runtime state is not reproduced; cells remain inert text during conversion |
| PDF | `.pdf` | `pdf` | Extracts existing text and tables | No built-in local OCR for scanned pages; multi-column order and complex tables require validation |
| Word | `.docx` | `docx` | Headings, lists, links, tables, images/alt text, and OMML math | Track changes, floating layout, and visual pagination are not faithfully reproduced |
| PowerPoint | `.pptx` | `pptx` | Slide text, tables, notes, and shape ordering | Animations and layout fidelity are lost; image description requires an LLM client |
| Excel | `.xlsx` | `xlsx` | Worksheets rendered as Markdown tables | Formulas, charts, merged cells, and formatting require source-level validation |
| Legacy Excel | `.xls` | `xls` | Worksheets rendered as Markdown tables | Legacy parser limitations; no visual workbook fidelity |
| Outlook message | `.msg` | `outlook` | Message headers and body | Attachments and rich formatting may need separate handling |
| Image | `.jpg`, `.jpeg`, `.png` | Core | Selected ExifTool metadata; optional LLM description | Built-in converter does not locally OCR text; image may be sent to an external LLM |
| Audio/video-audio | `.wav`, `.mp3`, `.m4a`, `.mp4` | `audio-transcription` | Metadata plus speech transcript | Transcription uses Google Web Speech through `SpeechRecognition`; content leaves the machine |
### Formats commonly overstated
- The 0.1.8 built-in `ImageConverter` accepts JPEG and PNG, not GIF or WebP.
- Built-in PDF conversion extracts a text layer; Tesseract is not part of MarkItDown's PDF path.
- The package does not promise page ranges, bounding boxes, coordinates, or pixel-faithful output.
- JSON and XML are text-based inputs, not schema-aware transformations.
- A successful conversion does not imply complete figure, equation, table, or reading-order recovery.
## PDF
### Built-in extraction
```python
from markitdown import MarkItDown
result = MarkItDown().convert_local("paper.pdf")
print(result.markdown)
```
Use for born-digital PDFs where text is selectable. MarkItDown 0.1.5 improved aligned/wide table output and partially numbered lists; 0.1.6 fixed linear memory growth across PDF pages.
### Scanned PDFs
Choose one:
1. `markitdown-ocr==0.1.1` with an approved vision provider
2. Azure Document Intelligence
3. Azure Content Understanding
4. A local OCR/layout parser when content cannot leave the environment
Do not claim OCR was performed unless the selected path actually supplied it.
### Validate
- Reading order in multi-column papers
- Equations, superscripts, and symbols
- Table headers and row alignment
- Figure captions and footnotes
- References and hyperlinks
- Missing pages or empty scanned sections
## DOCX
Install:
```bash
uv pip install "markitdown[docx]==0.1.8"
```
Version 0.1.2 added DOCX math-equation rendering. Conversion is semantic, not page-layout preserving.
Validate:
- Heading levels and list nesting
- Tables and merged cells
- OMML equations
- Hyperlinks and image alt text
- Footnotes/endnotes
- Tracked changes and comments
For custom Mammoth mapping:
```python
from markitdown import MarkItDown
converter = MarkItDown(style_map="p[style-name='Abstract'] => blockquote.abstract")
result = converter.convert_local("manuscript.docx")
```
## PPTX
Install:
```bash
uv pip install "markitdown[pptx]==0.1.8"
```
The converter orders shapes to approximate reading order and extracts textual slide content. Optional `llm_client`, `llm_model`, and `llm_prompt` values can describe image content.
Validate:
- Slide order and boundaries
- Speaker notes
- Grouped/overlapping shapes
- Tables and chart labels
- Images containing essential text
- Content conveyed only by position, color, or animation
## XLSX and XLS
Install:
```bash
uv pip install "markitdown[xlsx,xls]==0.1.8"
```
The result is useful for textual review and LLM ingestion, but it is not a workbook round trip.
Validate:
- Sheet names and order
- Hidden rows, columns, and sheets
- Merged cells
- Formula text versus cached/displayed values
- Date/number interpretation
- Charts, images, comments, and conditional formatting
The 0.1.8 XLSX converter reads **all worksheets** (`sheet_name=None`); hiding a
sheet in Excel is not an extraction filter. Inventory sheet visibility before
sharing the Markdown and use an explicitly selected workbook copy if only certain
sheets belong in the output.
Formula results depend on values cached in the workbook; MarkItDown does not
recalculate formulas. Missing or stale caches can yield blank or outdated cells.
For trusted workbooks, recalculate and save with a compatible spreadsheet engine
when current formula results are required, then compare key cells with the source.
For numeric analysis, read the workbook directly with a dataframe or spreadsheet library after using MarkItDown for orientation.
## Images
The built-in converter supports `.jpg`, `.jpeg`, and `.png`.
Without an LLM client, output may contain only selected metadata and can be empty when ExifTool is unavailable or the file has no relevant metadata.
```python
from markitdown import MarkItDown
result = MarkItDown(exiftool_path="/opt/homebrew/bin/exiftool").convert_local(
"figure.png"
)
```
The path above is illustrative; discover the executable with `shutil.which("exiftool")` or use its reviewed absolute path. Use only a trusted ExifTool executable. MarkItDown 0.1.3 added a safety requirement for ExifTool 12.24 or later.
Vision descriptions and OCR are external-processing paths; see `cloud_and_ocr.md`.
## Audio
Accepted extensions are `.wav`, `.mp3`, `.m4a`, and `.mp4`.
```bash
uv pip install "markitdown[audio-transcription]==0.1.8"
```
Install FFmpeg separately for MP3/M4A/MP4 decoding; the Python extra does not supply that executable. WAV can be decoded directly.
The tested `SpeechRecognition==3.17.0` legacy recognizer defaults to an HTTP Google Web Speech endpoint. This is not the authenticated Google Cloud Speech-to-Text API; do not send confidential recordings through this path.
The implementation converts supported audio to a `SpeechRecognition` input and calls `recognize_google()`. This is not offline transcription. Use a separately reviewed local or approved secure transcription workflow for confidential recordings.
The converter does not provide speaker diarization, timestamps, confidence values, or domain adaptation.
## YouTube
```bash
uv pip install "markitdown[youtube-transcription]==0.1.8"
markitdown "https://www.youtube.com/watch?v=VIDEO_ID" -o transcript.md
```
Behavior:
- Downloads the page
- Extracts title, description, and selected metadata
- Requests an available transcript
- Prefers English, then an available language, with translation fallback
Availability depends on YouTube, the video, geography, cookies/network policy, and transcript permissions.
## CSV, JSON, and XML
CSV has a dedicated table converter:
```python
result = MarkItDown().convert_local("measurements.csv")
```
JSON and XML are generally handled as text-like formats. If downstream work needs validated records, parse with `json`, `defusedxml`, or a schema-aware library rather than parsing the generated Markdown.
## ZIP and EPUB
ZIP conversion invokes MarkItDown recursively for archive members. Apply:
- Maximum archive size
- Maximum member count
- Maximum nested depth
- Compression-ratio limits
- Per-member type allowlists
Do not use conversion as an archive-security boundary.
EPUB conversion targets textual book structure. DRM-protected or fixed-layout publications may fail or lose essential visual information.
## Remote and Special Sources
`convert_uri()` accepts:
- `file:`
- `data:`
- `http:`
- `https:`
`file:` and `data:` are still potentially dangerous when user-controlled. `http:` and `https:` require SSRF, redirect, size, and timeout controls. See `security.md`.
## Azure Document Intelligence Format Set
The 0.1.8 integration supports:
- Documents: DOCX, PPTX, XLSX
- OCR/layout: PDF, JPEG, PNG, BMP, TIFF
- HTML is represented in the enum but is not in the converter's default file-type list
The API version now defaults to the installed SDK choice (`2024-11-30` with tested `azure-ai-documentintelligence==1.0.2`). Document bytes are sent to Azure.
## Azure Content Understanding Format Set
The 0.1.8 integration can route:
- Documents: PDF, DOCX, PPTX, XLSX, HTML, TXT, Markdown, RTF, XML
- Email: EML, MSG
- Images: JPEG, PNG, BMP, TIFF, HEIF/HEIC
- Video: MP4, M4V, MOV, AVI, MKV, WebM, FLV, WMV
- Audio: WAV, MP3, M4A, FLAC, OGG, AAC, WMA
Support here means Azure Content Understanding routing, not local built-in parsing. Each routed conversion is an external, potentially billable operation.
## Format Hints
When bytes lack a meaningful filename:
```python
from markitdown import MarkItDown, StreamInfo
with open("upload.bin", "rb") as stream:
result = MarkItDown().convert_stream(
stream,
stream_info=StreamInfo(
extension=".pdf",
mimetype="application/pdf",
filename="upload.pdf",
),
)
```
CLI equivalents:
```bash
markitdown < upload.bin -x .pdf -m application/pdf -o output.md
```
## Source Basis
- Official 0.1.8 README: https://github.com/microsoft/markitdown/blob/v0.1.8/README.md
- Built-in converter registry: https://github.com/microsoft/markitdown/blob/v0.1.8/packages/markitdown/src/markitdown/_markitdown.py
- Release history: https://github.com/microsoft/markitdown/releases
- SpeechRecognition 3.17.0 legacy Google request: https://github.com/Uberi/speech_recognition/blob/3.17.0/speech_recognition/recognizers/google.py
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 |