skills/markitdown/references/file_formats.md
This reference targets Microsoft MarkItDown 0.1.6. "Built-in" means the converter ships in the markitdown package; some built-ins still require an optional dependency extra.
# Full built-in feature set
uv pip install "markitdown[all]==0.1.6"
# Common document subset
uv pip install "markitdown[pdf,docx,pptx,xlsx]==0.1.6"
# Minimal package; suitable for core text/HTML/CSV/ZIP/EPUB/IPYNB paths
uv pip install "markitdown==0.1.6"
| 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 | https://www.youtube.com/watch?... | 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 | 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 |
ImageConverter accepts JPEG and PNG, not GIF or WebP.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.
Choose one:
markitdown-ocr==0.1.0 with an approved vision providerDo not claim OCR was performed unless the selected path actually supplied it.
Install:
uv pip install "markitdown[docx]==0.1.6"
Version 0.1.2 added DOCX math-equation rendering. Conversion is semantic, not page-layout preserving.
Validate:
For custom Mammoth mapping:
from markitdown import MarkItDown
converter = MarkItDown(style_map="p[style-name='Abstract'] => blockquote.abstract")
result = converter.convert_local("manuscript.docx")
Install:
uv pip install "markitdown[pptx]==0.1.6"
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:
Install:
uv pip install "markitdown[xlsx,xls]==0.1.6"
The result is useful for textual review and LLM ingestion, but it is not a workbook round trip.
Validate:
For numeric analysis, read the workbook directly with a dataframe or spreadsheet library after using MarkItDown for orientation.
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.
from markitdown import MarkItDown
result = MarkItDown(exiftool_path="/opt/homebrew/bin/exiftool").convert_local(
"figure.png"
)
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.
Accepted extensions are .wav, .mp3, .m4a, and .mp4.
uv pip install "markitdown[audio-transcription]==0.1.6"
The implementation converts supported audio to a SpeechRecognition input and calls recognize_google(). This is not offline transcription. Obtain approval before converting confidential recordings.
The converter does not provide speaker diarization, timestamps, confidence values, or domain adaptation.
uv pip install "markitdown[youtube-transcription]==0.1.6"
markitdown "https://www.youtube.com/watch?v=VIDEO_ID" -o transcript.md
Behavior:
Availability depends on YouTube, the video, geography, cookies/network policy, and transcript permissions.
CSV has a dedicated table converter:
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 conversion invokes MarkItDown recursively for archive members. Apply:
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.
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.
The 0.1.6 integration supports:
The default API version is 2024-07-31-preview. Document bytes are sent to Azure.
The 0.1.6 integration can route:
Support here means Azure Content Understanding routing, not local built-in parsing. Each routed conversion is an external, potentially billable operation.
When bytes lack a meaningful filename:
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:
markitdown < upload.bin -x .pdf -m application/pdf -o output.md