MarkItDown
MarkItDown explained: turn documents into useful Markdown
Understand what Microsoft MarkItDown preserves, where conversion loses information, and how to choose a first document for an LLM ingestion pipeline.
What you will learn
- Preserved text structure is different from preserved visual meaning.
- Optional converters change the capabilities of an installation.
- Keep the original document when readers need visual evidence.
Before you start
- Basic Python and command-line usage
- A non-sensitive document whose contents you can verify
Use the chapter checklist to explain and verify this part of a document ingestion workflow.
Key takeaways
- Preserved text structure is different from preserved visual meaning.
- Optional converters change the capabilities of an installation.
- Keep the original document when readers need visual evidence.
A document adapter for text workflows
MarkItDown is a Python utility that converts supported documents and media into Markdown for text analysis and language-model workflows. Its purpose is to expose readable structure: headings, lists, links and tables. It is useful when an application needs one downstream text format despite receiving several different file formats.
The distinction between structure and appearance matters. A slide can contain meaningful text while depending on position, color and an illustration to express its argument. A Markdown conversion can preserve the words without preserving that argument. Keep the original available when layout or visual evidence affects interpretation.
Capabilities depend on the installed conversion path
The captured README lists Office documents, PDFs, images, audio, HTML, archives and several text formats. That list describes the project as a whole. Optional package extras and plugins determine which conversion paths are available in a particular installation; a minimal environment and an all-extras environment are different products operationally.
Ordinary document extraction need not involve a language-model API. The README separately documents model-assisted image descriptions and cloud document services. A team can begin with local conversion and choose those additions only for a defined requirement, with their latency, data transfer and service configuration accounted for separately.
Pick an example whose meaning you can check
Start with a short document containing a heading, a paragraph, a link and a small table with known values. Compare the Markdown against those facts. Looking only at whether the command exits successfully misses empty output, lost columns and text that appears in an incorrect reading order.
Choose MarkItDown when normalized text is the required output. Choose a layout-preserving export when the deliverable is a faithful document for people to read. A retrieval system may need both: Markdown for indexing and the original page or slide for evidence. The converter does not make that product decision automatically.
Implementation steps
- 1
Select a short, non-sensitive document with known facts.
- 2
Install only the format dependencies needed for that document.
- 3
Compare headings, table values and reading order with the original.
Copy-ready example
from markitdown import MarkItDown
converter = MarkItDown(enable_plugins=False)
result = converter.convert_local("example.docx")
print(result.markdown)Frequently asked questions
Does MarkItDown require an LLM?
Basic local conversion does not require a model client. Model-assisted descriptions and cloud services are separate optional paths.
Does Markdown preserve a PDF page exactly?
No. Text and structural extraction are not a substitute for preserving page layout, diagrams or visual evidence.
Sources
- Pinned sourceSource checked 2026-09-07
- Core dispatcherSource checked 2026-09-07
- Plain-text converterSource checked 2026-09-07
- Public exportsSource checked 2026-09-07