How MarkItDown Transforms Docs to Markdown and Powers AI Pipelines

Recently, Microsoft’s MarkItDown library has attracted wide attention on GitHub, quickly gaining over 20,000 stars. MarkItDown is a powerful Python library that can convert many common file formats (PDF, PowerPoint, Word, Excel, images, audio, HTML, etc.) into Markdown.

Advantages and Features of MarkItDown

Compared with other conversion tools (e.g., Unstructured, Marker), MarkItDown delivers superior conversion results, especially for Office documents, accurately preserving core content and formatting while presenting it in concise Markdown syntax, which helps large language models better understand the source material.

Simple Example: Converting an Excel File

First, install the MarkItDown library:

<code>pip install markitdown</code>

Then use the following code to perform the conversion:

<code>from markitdown import MarkItDown
# Initialize MarkItDown object
markitdown = MarkItDown()
# Convert Excel file to Markdown format
result = markitdown.convert("test.xlsx")
# Print the converted Markdown content
print(result.text_content)</code>

This easily converts an Excel document into Markdown.

Because MarkItDown is a Python package, using it directly from other programming languages is not very convenient. Therefore, the author wrapped MarkItDown into a REST API service, also adding PDF‑to‑Markdown support, allowing developers of any language to call the service.

Using MarkItDown via REST API

1. Run the Docker container:

<code>docker run -p 8000:8000 pig4cloud/markitdown</code>

2. Test the API with curl, uploading a Word file for conversion:

<code>curl -X 'POST' \
  'http://localhost:8000/upload/' \
  -H 'Content-Type: multipart/form-data' \
  -F '[email protected]'

# The API returns the converted Markdown text
{
  "text": "\n## 核心技术栈升级\n\n..."
}</code>

The returned Markdown can be embedded directly into documents or further processed.

Advanced Use: Enhancing Conversion with Vision Models

MarkItDown can be combined with large‑vision models to improve parsing of images and complex documents. Start the service with the desired model:

<code>docker run -d \
  -p 8000:8000 \
  -e API_KEY=gitee_ai_key \
  -e MODEL=InternVL2_5-26B \
  -e BASE_URL=https://ai.gitee.com/v1 \
  pig4cloud/markitdown</code>

The example uses Gitee AI’s InternVL2_5-26B visual model, but other models such as qwen‑vl or local models (e.g., ollama run minicpm-v:8b) can also be used.

Swagger UI is available at http://0.0.0.0:9527/swagger-ui.html .

Summary and Outlook

Although MarkItDown has made significant progress in converting many file formats, its support for legacy Office files (.doc, .xls) and scanned PDFs remains limited (the enhanced project adds some support). For complex reports, extraction quality may be lower, especially with unstructured data.

Nevertheless, in Retrieval‑Augmented Generation (RAG) systems, MarkItDown serves as an effective initial data conversion tool, greatly aiding the construction of smarter data processing and generation pipelines. As its features continue to evolve, MarkItDown will become an even more powerful utility for developers needing document format conversion.

If you are interested in AI development or data processing, give MarkItDown a try—its potential is especially promising when combined with large language models.

Server API source code: https://gitee.com/log4j/office2md