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.
Changelog

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.
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:
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):
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.
- zsh
- bash
1. Create the file in ~/.zsh/fns/:
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:
for fn_file in ~/.zsh/fns/*.zsh; do
source "$fn_file"
done
3. Open a new terminal (or run exec zsh).
1. Create the file in ~/.bash/fns/:
Need help here? Click the "Help" button above for setup instructions.
2. Load the folder from ~/.bashrc. Add at the end of ~/.bashrc (the -r test keeps an empty folder from printing an error):
for fn_file in ~/.bash/fns/*.sh; do
[[ -r "$fn_file" ]] && source "$fn_file"
done
3. Open a new terminal (or run exec bash).
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:
- 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).
Loading comments…





