Skip to main content

Markitdown - Convert files and MS Office documents to Markdown

Easily convert MS Office documents (Word, Excel) and PDFs into Markdown format with Microsoft's Markitdown tool. Includes step-by-step instructions for installation via Docker.

· 6 min read
View raw
Christophe
Markdown, WSL and Docker lover ~ Insatiable curious.
Cet article existe aussi en français — lire la version française.

Changelog

Latest
md-convert is now a shell function for zsh and bash (~/.zsh/fns or ~/.bash/fns), the Dockerfile lives in ~/tools/markitdown; compose.yaml is gone.
markitdown updated from v0.1.5 to v0.1.7; Dockerfile and AlertBox version reference updated.

Markitdown - Convert files and MS Office documents to Markdown

⚡
TL;DR
This post explores how to use Microsoft's Markitdown, a highly capable utility for converting files like Word documents, Excel spreadsheets, and PDFs into clean Markdown format. To keep your local system clean and avoid managing Python dependencies globally, the author provides a step-by-step guide to setting up the tool inside an isolated, lightweight Docker container. The tutorial covers creating a customized Dockerfile and an md-convert shell function, for zsh or bash. This setup allows you to securely and effortlessly run document conversions from any directory directly via your terminal.

Recently, a friend told me about a tool from Microsoft called Markitdown: a utility for converting PDF and MS Office files (like .docx or .xlsx) into Markdown. Looking at the GitHub repository, it seems highly capable. They claim it converts PDFs, PowerPoint, Word, Excel, images, audio, HTML, and text-based formats like CSV, JSON, or XML—and even iterates through ZIP files. That is a huge promise! Since it is always useful to quickly convert .docx files from colleagues who do not write in Markdown, I wanted to rigorously test it.

In this article, we'll create a Docker image and a small conversion function called md-convert that you'll be able to call from everywhere on your disk to easily convert docx, xlsx and pdf files to Markdown thanks to Markitdown.

Just need an Excel range or a CSV file as a Markdown table?

Markitdown is a general-purpose, heavier tool. If your need is narrower — just turning a copied Excel range or a CSV file into a Markdown table — my XLS2MD and CSV2MD online tools are quicker, no Docker required.

First Conversion​

Once the image and the md-convert function are installed (covered under Installation below), converting a document is one command from any folder:

>user@machine: ~/yourproject

Why This Approach​

As always, I'll first create a Docker image so I don't need to install Python on my machine nor manage the utility and all its dependencies.

I love Docker also for this

This is exactly why Docker is indispensable: complete isolation. Everything runs within the container. Once I am done experimenting, I can delete the image, leaving nothing on my disk except the Dockerfile needed to recreate it on demand. If that reasoning is new to you, Docker - Explain me like I'm five - What's Docker for? makes the case with a cooking analogy.

Installation​

Create our Docker image​

The Dockerfile gets a permanent home, ~/tools/markitdown, so the image can be rebuilt any time (new machine, docker image prune, a new Markitdown version):

📦 Project setup: ~/tools/markitdown
Help

Need help here? Click the "Help" button above for setup instructions.

Supported extensions

See the pip install --prefix=/python "markitdown[docx,xlsx,pdf]==0.1.7" line in our Dockerfile; we could replace docx,xlsx,pdf by all to be able to convert from any extensions supported by Markitdown but our final Docker image will be bigger in size.

Or, simply add any additional extensions you need. Refer to the official documentation for this.

Build it:

docker build -t markitdown ~/tools/markitdown

Make md-convert available everywhere​

What turns that image into a command is one function, in its own file in a folder your shell loads at startup (the organisation explained in my modular ZSH workflow). It mounts the current folder into the container, read-only everywhere else, unprivileged, and thrown away after each conversion:

# md-convert: convert a document of the current folder to Markdown with the
# isolated markitdown Docker image. Works in zsh and bash: save it as
# ~/.zsh/fns/md-convert.zsh or ~/.bash/fns/md-convert.sh (see the article).
#
# md-convert report.docx > report.md
#
# The current folder is the only thing the container sees; everything else is
# read-only, unprivileged, and thrown away after the conversion.
md-convert() {
local image="markitdown"
# Permanent home of the Dockerfile, so the image can always be rebuilt.
local build_dir="${HOME}/tools/markitdown"
# Shown as is in the messages, so the command can be copied for any user.
# shellcheck disable=SC2016
local build_dir_shown='${HOME}/tools/markitdown'
if ! command -v docker >/dev/null 2>&1; then
printf '\e[31mError: docker is not installed or not in your PATH.\e[0m\n' >&2
return 1
fi
if ! docker image inspect "${image}" >/dev/null 2>&1; then
printf '\e[31mError: the Docker image "%s" does not exist on this machine.\e[0m\n\n' "${image}" >&2
printf 'How to continue:\n' >&2
if [[ -f "${build_dir}/Dockerfile" ]]; then
printf ' 1. docker build -t %s "%s"\n' "${image}" "${build_dir_shown}" >&2
printf ' 2. Run your md-convert command again.\n' >&2
else
printf ' 1. Get the Dockerfile from https://www.avonture.be/blog/markitdown\n' >&2
printf ' and save it as %s/Dockerfile\n' "${build_dir_shown}" >&2
printf ' 2. docker build -t %s "%s"\n' "${image}" "${build_dir_shown}" >&2
printf ' 3. Run your md-convert command again.\n' >&2
fi
return 1
fi
docker run --rm -i \
-v "${PWD}:/workspace" \
-w /workspace \
--read-only \
--tmpfs /tmp:size=64m,noexec,nosuid \
--tmpfs /run:size=16m \
--cap-drop ALL \
--security-opt no-new-privileges:true \
-u "$(id -u):$(id -g)" \
"${image}" "$@"
}

This function wraps the markitdown Docker image to safely convert documents to Markdown from your current folder. It first checks that Docker is installed and the image exists (with helpful setup instructions if not), then runs the container with strict security restrictions—the container can only see your current folder, runs as your user, and everything is thrown away when done.

The code is the same for zsh and bash; only the folder and the loader differ.

1. Create the file in ~/.zsh/fns/:

📦 Project setup: ~/.zsh/fns
Help

Need help here? Click the "Help" button above for setup instructions.

2. Load the folder from ~/.zshrc. Already done if you followed one of my "Ollama daily use" articles. Otherwise, add at the end of ~/.zshrc:

~/.zshrc
for fn_file in ~/.zsh/fns/*.zsh; do
source "$fn_file"
done

3. Open a new terminal (or run exec zsh).

Check that the shell knows the function: type md-convert must answer md-convert is a shell function.

If the image is missing, md-convert doesn't fail with a cryptic Docker error: it prints the exact docker build command to run, or, when ~/tools/markitdown/Dockerfile is gone too, points back to this article.

Coming from the previous version of this article?

It installed md-convert as a script in /usr/local/bin/. Remove it (sudo rm /usr/local/bin/md-convert): the function takes over, and the old script would otherwise linger on your disk.

Conclusion​

Thanks to Markitdown and the md-convert function we just built, converting office documents into clean Markdown is now effortless, secure, and native to your terminal.

Check the official repository for the complete list of supported file formats:

  • PDF
  • PowerPoint
  • Word
  • Excel
  • Images (EXIF metadata and OCR)
  • Audio (EXIF metadata and speech transcription)
  • HTML
  • Text-based formats (CSV, JSON, XML)
  • ZIP archives (iterates recursively over contents)
  • YouTube URLs
  • EPUBs
  • ... and more!

In this guide, we deliberately focused on compiling only the extensions for Word, Excel, and PDF ([docx,xlsx,pdf]) to keep our Docker image lightweight and strictly scoped. However, you can easily expand the tool's capabilities to suit your needs. Simply adjust the pip install extras in ~/tools/markitdown/Dockerfile and rebuild your image.

Refer to the Optional Dependencies section in the official documentation to explore the full potential of this utility.

Complex PDFs, dense tables, scanned pages?

Markitdown parses each format with a dedicated library, which is fast and light but sometimes flattens a complex layout. When the document really matters, I now reach for a second, heavier image built the exact same way: see Docling - Convert PDF, Word, PowerPoint, Excel and HTML to Markdown, GPU-Accelerated, which runs real layout and table-structure models (on the GPU, if you have one).


Was this article helpful?
Did you try the steps in this article?
🦋 Join the conversation on BlueskyRequires a free Bluesky account to like, repost or comment. This block talks to Bluesky's public API directly from your browser (no cookies, no sign-in) — that means your IP address reaches Bluesky's servers just by this section loading.

Loading comments…