MarkItDown là gì? Phân tích repo microsoft/markitdown và hướng dẫn sử dụng

MarkItDown là gì? Phân tích repo microsoft/markitdown và hướng dẫn sử dụng dễ hiểu

Ảnh trích xuất từ GitHub Open Graph preview của repo microsoft/markitdown. Ảnh không phải SVG.¹

Tóm tắt nhanh

MarkItDown là một công cụ Python của Microsoft dùng để chuyển nhiều loại file sang Markdown. Repo chính thức mô tả MarkItDown là một tiện ích Python nhẹ để chuyển nhiều định dạng file sang Markdown cho LLM và các pipeline phân tích văn bản.²

Nói đơn giản: nếu bạn có file PDF, Word, Excel, PowerPoint, HTML, CSV, JSON, XML, EPUB, ZIP, ảnh, audio hoặc YouTube URL, MarkItDown giúp biến nội dung đó thành Markdown dễ đưa vào ChatGPT, Claude, RAG system, search index, vector database hoặc script phân tích tài liệu.

MarkItDown không nhắm tới việc giữ bố cục đẹp tuyệt đối như tài liệu gốc. README nói output thường khá dễ đọc, nhưng mục tiêu chính là để công cụ phân tích văn bản tiêu thụ; vì vậy nó ưu tiên giữ cấu trúc quan trọng như heading, list, table, link và nội dung chính ở dạng Markdown.²

MarkItDown giải quyết vấn đề gì?

LLM và hệ thống RAG thường làm việc tốt với text rõ ràng. Nhưng dữ liệu thực tế lại nằm trong nhiều định dạng khác nhau: báo cáo PDF, file Word, slide PowerPoint, bảng Excel, trang HTML, CSV/JSON/XML, email Outlook, ảnh, audio, ZIP, YouTube transcript hoặc EPUB.

Nếu xây pipeline AI mà không có công cụ chuyển đổi thống nhất, bạn phải viết nhiều converter riêng cho từng định dạng. MarkItDown gom các converter phổ biến vào một công cụ duy nhất và xuất ra Markdown.

Vì sao lại là Markdown?

Markdown gần với plain text, ít markup, nhưng vẫn biểu diễn được cấu trúc tài liệu như heading, list, table và link. README cũng nêu rằng các LLM lớn như GPT-4o thường hiểu Markdown tốt và Markdown tương đối tiết kiệm token.²

MarkItDown hỗ trợ định dạng nào?

README liệt kê các nhóm định dạng chính mà MarkItDown hỗ trợ:²

• PDF
• PowerPoint
• Word
• Excel
• Images: EXIF metadata và OCR
• Audio: EXIF metadata và speech transcription
• HTML
• CSV, JSON, XML
• ZIP files, bằng cách lặp qua nội dung bên trong
• YouTube URLs
• EPUBs
• và nhiều định dạng khác

Không phải mọi dependency đều được cài mặc định. MarkItDown dùng optional dependencies để bạn cài đúng nhóm định dạng cần dùng.

MarkItDown không phải là gì?

Nếu mục tiêu là “chuyển file thành Markdown đủ tốt để LLM đọc”, MarkItDown rất phù hợp. Nếu mục tiêu là “giữ nguyên 100% bố cục”, cần kiểm tra kỹ vì đó không phải mục tiêu chính của repo.

Cài đặt MarkItDown

MarkItDown yêu cầu Python 3.10 trở lên.²

Tạo virtual environment:

python -m venv .venv
source .venv/bin/activate

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Cài toàn bộ tính năng:

pip install "markitdown[all]"

Chỉ cài một số định dạng:

pip install "markitdown[pdf,docx,pptx]"

README liệt kê các extra như [pptx], [docx], [xlsx], [xls], [pdf], [outlook], [az-doc-intel], [az-content-understanding], [audio-transcription], [youtube-transcription] và [all].²

Cài từ source:

git clone https://github.com/microsoft/markitdown.git
cd markitdown
pip install -e "packages/markitdown[all]"

Dùng bằng command line

Chuyển PDF sang Markdown:

markitdown report.pdf > report.md

Ghi ra file bằng -o:

markitdown report.pdf -o report.md

Dùng pipe:

cat report.pdf | markitdown > report.md

Một số ví dụ khác:

markitdown document.docx -o document.md
markitdown slides.pptx -o slides.md
markitdown workbook.xlsx -o workbook.md
markitdown page.html -o page.md
markitdown data.json -o data.md
markitdown archive.zip -o archive.md

Nếu đã cài extra phù hợp, có thể chuyển YouTube URL:

markitdown "https://www.youtube.com/watch?v=VIDEO_ID" -o video.md

Dùng bằng Python API

Ví dụ cơ bản trong README:²

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)
result = md.convert("test.xlsx")

print(result.text_content)

Lưu ra file:

from pathlib import Path
from markitdown import MarkItDown

converter = MarkItDown()
result = converter.convert("report.pdf")

Path("report.md").write_text(result.text_content, encoding="utf-8")

Chuyển nhiều file trong thư mục:

from pathlib import Path
from markitdown import MarkItDown

converter = MarkItDown()
input_dir = Path("documents")
output_dir = Path("markdown")
output_dir.mkdir(exist_ok=True)

for path in input_dir.iterdir():
    if path.is_file():
        try:
            result = converter.convert(str(path))
            out = output_dir / f"{path.stem}.md"
            out.write_text(result.text_content, encoding="utf-8")
            print("Converted:", path)
        except Exception as exc:
            print("Failed:", path, exc)

Dùng LLM để mô tả ảnh

README nói MarkItDown có thể dùng Large Language Models để mô tả ảnh, hiện cho image files và PowerPoint, bằng cách truyền llm_client và llm_model.²

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()

md = MarkItDown(
    llm_client=client,
    llm_model="gpt-4o",
    llm_prompt="Mô tả hình ảnh ngắn gọn, tập trung vào thông tin có ích cho tìm kiếm.",
)

result = md.convert("example.jpg")
print(result.text_content)

Cách này hữu ích khi ảnh hoặc slide có nội dung quan trọng nhưng extractor thông thường không đọc được.

Plugin OCR cho PDF/DOCX/PPTX/XLSX

Repo có package markitdown-ocr. README plugin nói nó dùng LLM Vision để trích xuất text từ ảnh nhúng trong PDF, DOCX, PPTX và XLSX, dùng cùng pattern llm_client / llm_model của MarkItDown.³

Cài đặt:

pip install markitdown-ocr
pip install openai

CLI:

markitdown document.pdf --use-plugins --llm-client openai --llm-model gpt-4o

Python:

from markitdown import MarkItDown
from openai import OpenAI

md = MarkItDown(
    enable_plugins=True,
    llm_client=OpenAI(),
    llm_model="gpt-4o",
)

result = md.convert("document_with_images.pdf")
print(result.text_content)

Theo README plugin, nếu không có llm_client, plugin vẫn load nhưng OCR bị bỏ qua và converter built-in được dùng.³

Plugin system

MarkItDown hỗ trợ plugin bên thứ ba. README nói plugin bị tắt mặc định.²

Liệt kê plugin:

markitdown --list-plugins

Dùng plugin:

markitdown --use-plugins path-to-file.pdf

Sample plugin cho thấy một plugin cần tạo class kế thừa DocumentConverter, implement accepts() và convert(), rồi export register_converters() qua entrypoint markitdown.plugin trong pyproject.toml.⁴

Ý nghĩa thực tế: nếu công ty có định dạng riêng như .rtf, invoice export, report format hoặc dữ liệu nội bộ, bạn có thể viết converter riêng và gắn vào MarkItDown.

Azure Document Intelligence và Azure Content Understanding

MarkItDown có thể dùng Azure cloud services cho trường hợp cần chất lượng cao hơn.

Azure Document Intelligence:

markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"

Python:

from markitdown import MarkItDown

md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("test.pdf")
print(result.text_content)

Azure Content Understanding:

markitdown path-to-file.pdf --use-cu --cu-endpoint "<content_understanding_endpoint>"

Python:

from markitdown import MarkItDown

md = MarkItDown(cu_endpoint="<content_understanding_endpoint>")
result = md.convert("report.pdf")
print(result.markdown)

Với custom analyzer:

md = MarkItDown(
    cu_endpoint="<content_understanding_endpoint>",
    cu_analyzer_id="my-invoice-analyzer",
)

result = md.convert("invoice.pdf")
print(result.markdown)

README lưu ý mỗi lần convert() với format được route qua Content Understanding là billable Azure API call, nên cần giới hạn file type nếu muốn kiểm soát chi phí.²

MarkItDown MCP là gì?

markitdown-mcp là MCP server cho MarkItDown. README package này nói nó cung cấp server nhẹ qua STDIO, Streamable HTTP và SSE, expose một tool duy nhất: convert_to_markdown(uri), trong đó URI có thể là http:, https:, file: hoặc data:.⁵

Cài đặt:

pip install markitdown-mcp

Chạy STDIO:

markitdown-mcp

Chạy HTTP/SSE local:

markitdown-mcp --http --host 127.0.0.1 --port 3001

Nếu Claude Desktop, Cursor hoặc agent hỗ trợ MCP, bạn có thể cho agent một tool chuyển tài liệu sang Markdown.

Dùng MarkItDown MCP với Claude Desktop bằng Docker

README của markitdown-mcp khuyến nghị dùng Docker với Claude Desktop.⁵

Build image:

docker build -t markitdown-mcp:latest .

Cấu hình Claude Desktop:

{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "markitdown-mcp:latest"]
    }
  }
}

Nếu muốn cho container đọc file local:

{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/home/user/data:/workdir",
        "markitdown-mcp:latest"
      ]
    }
  }
}

Sau đó agent có thể gọi:

convert_to_markdown("file:///workdir/report.pdf")

Docker cho MarkItDown CLI

README repo chính có ví dụ Docker:²

docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

Dockerfile chính dùng python:3.13-slim-bullseye, cài ffmpeg và exiftool, cài markitdown[all] và sample plugin, rồi chạy entrypoint markitdown.⁶

Dùng Docker khi cần tránh dependency conflict, chạy batch job hoặc muốn cô lập quyền file/network.

Triển khai MarkItDown trong pipeline RAG

Pipeline cơ bản:

File gốc
  ↓
MarkItDown
  ↓
Markdown text
  ↓
Chunking
  ↓
Embedding
  ↓
Vector database
  ↓
RAG answer

Ví dụ:

from pathlib import Path
from markitdown import MarkItDown

converter = MarkItDown()
docs_dir = Path("raw_docs")
md_dir = Path("markdown_docs")
md_dir.mkdir(exist_ok=True)

for file in docs_dir.glob("*"):
    if not file.is_file():
        continue

    result = converter.convert(str(file))
    md_file = md_dir / f"{file.stem}.md"
    md_file.write_text(result.text_content, encoding="utf-8")

Sau đó dùng Markdown này để chunk, embedding và đưa vào vector database.

Triển khai server-side an toàn

README cảnh báo MarkItDown thực hiện I/O với quyền của process hiện tại. Giống open() hoặc requests.get(), nó có thể truy cập tài nguyên mà process có quyền. README khuyến nghị sanitize input trong môi trường không tin cậy và gọi hàm convert_* hẹp nhất phù hợp, ví dụ convert_stream() hoặc convert_local().⁷

Nếu triển khai MarkItDown làm backend cho người dùng upload file:

• không cho người dùng nhập đường dẫn file tùy ý;
• không fetch URL tùy ý nếu chưa lọc;
• chặn private IP, loopback, link-local, metadata service;
• giới hạn file size;
• giới hạn loại file;
• chạy trong container hoặc sandbox;
• dùng user không có quyền đọc secret;
• tắt network nếu không cần fetch URL;
• scan malware nếu nhận file từ internet;
• log lỗi nhưng không log nội dung nhạy cảm.

Các hàm convert nên dùng

README khuyến nghị không nhất thiết dùng convert() rộng nếu đã biết nguồn input.⁷

Quy tắc dễ nhớ: trong production, hãy dùng hàm hẹp nhất có thể.

Khi nào nên dùng MarkItDown?

Nên dùng khi:

• cần chuyển tài liệu sang Markdown cho LLM;
• cần chuẩn bị dữ liệu cho RAG;
• muốn batch convert PDF/DOCX/PPTX/XLSX;
• cần một CLI nhanh để lấy text từ file;
• muốn agent MCP đọc file dưới dạng Markdown;
• muốn tích hợp Azure Document Intelligence hoặc Content Understanding;
• muốn viết plugin cho format nội bộ.

Không nên dùng nếu:

• cần giữ nguyên layout chính xác như bản gốc;
• tài liệu scan chất lượng thấp nhưng không dùng OCR/cloud converter;
• input không tin cậy mà chưa sandbox;
• cần một trình soạn thảo Markdown;
• cần trình render PDF/HTML đẹp cho người dùng cuối.

So sánh nhanh

Checklist triển khai

• Cài trong virtual environment.
• Chỉ cài extra cần dùng nếu muốn nhẹ.
• Dùng CLI để test từng định dạng trước.
• Với RAG, lưu Markdown trung gian để debug.
• Với PDF scan, cân nhắc OCR plugin hoặc Azure.
• Với server public, không cho người dùng nhập URL/path tùy ý.
• Với MCP, chỉ bind localhost nếu chưa có auth.
• Với Docker, mount đúng thư mục cần đọc, không mount toàn bộ home.
• Với plugin, bật --use-plugins rõ ràng.
• Với Azure CU, kiểm soát chi phí billable API call.

FAQ

MarkItDown là gì?

MarkItDown là công cụ Python của Microsoft để chuyển nhiều loại file và tài liệu Office sang Markdown cho LLM và pipeline phân tích văn bản.²

MarkItDown có hỗ trợ PDF không?

Có. README liệt kê PDF trong nhóm định dạng được hỗ trợ; để cài dependency PDF riêng có thể dùng pip install "markitdown[pdf]" hoặc cài tất cả bằng markitdown[all].²

MarkItDown có chuyển Word và PowerPoint không?

Có. MarkItDown hỗ trợ Word và PowerPoint; các extra tương ứng là [docx] và [pptx].²

MarkItDown có OCR không?

Có hỗ trợ hình ảnh ở mức metadata/OCR theo README, và có plugin markitdown-ocr dùng LLM Vision để OCR ảnh nhúng trong PDF, DOCX, PPTX và XLSX.²³

MarkItDown có dùng được với Claude Desktop hoặc MCP client không?

Có. Package markitdown-mcp cung cấp MCP server với tool convert_to_markdown(uri).⁵

Có nên expose MarkItDown MCP ra internet không?

Không nên. README của markitdown-mcp cảnh báo server không có authentication và mặc định bind localhost; không bind sang interface khác nếu chưa hiểu rõ rủi ro bảo mật.⁵

Kết luận

microsoft/markitdown rất hữu ích nếu bạn làm việc với LLM, RAG hoặc phân tích tài liệu. Nó không cố biến tài liệu thành bản trình bày đẹp tuyệt đối; nó tập trung chuyển nhiều định dạng phổ biến sang Markdown để model đọc dễ hơn và giữ được cấu trúc quan trọng.

Cách bắt đầu đơn giản nhất là cài pip install "markitdown[all]", chạy markitdown file.pdf -o file.md, rồi kiểm tra output. Khi dùng production, điểm quan trọng nhất là bảo mật: kiểm soát file path, URL, quyền I/O, sandbox/container và chỉ dùng API chuyển đổi hẹp nhất phù hợp với use case.

Nguồn tham khảo

Footnotes

1. GitHub Open Graph preview image for microsoft/markitdown. https://opengraph.githubassets.com/markitdown-guide/microsoft/markitdown ↩

2. Microsoft MarkItDown README. https://raw.githubusercontent.com/microsoft/markitdown/main/README.md ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹ ↩¹² ↩¹³ ↩¹⁴ ↩¹⁵

3. packages/markitdown-ocr/README.md. https://raw.githubusercontent.com/microsoft/markitdown/main/packages/markitdown-ocr/README.md ↩ ↩² ↩³

4. packages/markitdown-sample-plugin/README.md. https://raw.githubusercontent.com/microsoft/markitdown/main/packages/markitdown-sample-plugin/README.md ↩

5. packages/markitdown-mcp/README.md. https://raw.githubusercontent.com/microsoft/markitdown/main/packages/markitdown-mcp/README.md ↩ ↩² ↩³ ↩⁴

6. MarkItDown Dockerfile. https://raw.githubusercontent.com/microsoft/markitdown/main/Dockerfile ↩

7. Microsoft MarkItDown README, Security Considerations. https://raw.githubusercontent.com/microsoft/markitdown/main/README.md ↩ ↩²