Markitdown CLI

MarkItDown CLI Usage Guide

MarkItDown is a command-line tool for converting many file and URL inputs into Markdown. It works well for PDFs, Office documents, HTML, feeds, archives, and several optional plugin-backed workflows.

Basic Usage

# Convert a file to stdout
markitdown document.pdf

# Save Markdown to a file
markitdown document.pdf > document.md
markitdown document.pdf -o document.md

# Convert a URL
markitdown https://example.com/report.pdf
markitdown https://example.com/article -o article.md

# Read from stdin with an explicit type hint
cat page.html | markitdown -x html
cat payload | markitdown -m text/html

Common CLI Flags

Supported Inputs

Typical direct inputs include:

• PDF, DOCX, PPTX, XLSX, XLS, EPUB, MSG
• HTML pages, feed URLs, and some specialized web handlers
• CSV, JSON, XML, plain text, and Markdown
• ZIP archives
• Images and audio when the required optional dependencies are installed

High-Frequency Patterns

Batch conversion

# Convert all DOCX files in the current directory
for f in *.docx; do
  markitdown "$f" -o "${f%.docx}.md"
done

# Convert all XLSX files recursively
find . -name "*.xlsx" -exec sh -c 'markitdown "$1" -o "${1%.xlsx}.md"' _ {} \;

Piping and chaining

markitdown report.pdf | grep "revenue"
markitdown data.xlsx | head -50
curl -s https://example.com/page.html | markitdown -x html

Stdin hints

When the input comes from stdin, MarkItDown cannot reliably infer the format on its own. Add -x or -m:

cat mystery_file | markitdown -x pdf
cat spreadsheet.bin | markitdown -m application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
cat text_payload | markitdown -x csv -c UTF-8

Plugins, OCR, and Azure

• OCR should be treated as a plugin-backed capability rather than an official built-in extra documented here.
• If an OCR plugin is installed, discover it with --list-plugins and enable it with --use-plugins.
• Azure Document Intelligence is a first-class path for complex scanned documents. Use -d -e.
• In Xpert's MarkItDown middleware, the relevant official extras are values such as all, pdf, docx, pptx, xlsx, xls, outlook, az-doc-intel, audio-transcription, and youtube-transcription.

# Discover installed plugins
markitdown --list-plugins

# Use installed plugins, for example an OCR plugin
markitdown --use-plugins scanned.pdf -o scanned.md

# Use Azure Document Intelligence
markitdown -d -e "https://your-resource.cognitiveservices.azure.com/" complex.pdf -o complex.md

Format-Specific Notes

• PDF: Text PDFs usually work directly. For scanned PDFs, prefer Azure Document Intelligence or an installed OCR plugin.
• DOCX / PPTX / XLSX: Good defaults for headings, lists, slides, and tables, but review the output for complex layouts.
• HTML / URL: Works best when the content is either a file path or a fetchable URL. For stdin, add -x html or -m text/html.
• Images: Core behavior is often metadata-oriented. OCR or richer extraction usually depends on installed plugins or additional services.
• Audio: Requires optional dependencies such as audio-transcription or all.

Troubleshooting

• Empty output from stdin: add -x or -m so MarkItDown knows the input type.
• Scanned PDF is missing text: use -d -e for Azure Document Intelligence, or enable the installed OCR plugin with --use-plugins.
• A format is unsupported: verify the input really matches the hinted type and that the relevant optional dependencies are installed.
• Output is very large: save it with -o or > first, then inspect the result with other shell tools.