Markitdown - Convertir des fichiers et des documents MS Office en Markdown

Récemment, un ami m'a parlé d'un outil de Microsoft appelé Markitdown : un utilitaire pour convertir des PDF et des fichiers MS Office (comme .docx ou .xlsx) en Markdown. En regardant le repository GitHub, il a l'air très costaud. Ils annoncent la conversion des PDF, PowerPoint, Word, Excel, images, audio, HTML et des formats texte comme CSV, JSON ou XML — et même le parcours des fichiers ZIP. C'est une sacrée promesse ! Comme il est toujours utile de convertir rapidement les .docx de collègues qui n'écrivent pas en Markdown, je voulais le tester sérieusement.

Dans cet article, nous allons créer une image Docker et une petite fonction de conversion appelée md-convert, appelable depuis n'importe où sur votre disque, pour convertir facilement des fichiers docx, xlsx et pdf en Markdown grâce à Markitdown.

Première conversion​

Une fois l'image et la fonction md-convert installées (voir la section Installation plus bas), convertir un document tient en une commande, depuis n'importe quel dossier :

$ cd ~/documents/

$ md-convert sample.docx > sample.md
$ md-convert budget.xlsx > budget.md
$ md-convert user_guide.pdf > user_guide.md
▋

Pourquoi cette approche​

Comme toujours, je commence par créer une image Docker pour ne pas devoir installer Python sur ma machine ni gérer l'utilitaire et toutes ses dépendances.

Installation​

Créer notre image Docker​

Le Dockerfile obtient une adresse définitive, ~/tools/markitdown, pour pouvoir reconstruire l'image à tout moment (nouvelle machine, docker image prune, nouvelle version de Markitdown) :

Construisez-la :

docker build -t markitdown ~/tools/markitdown

Rendre md-convert disponible partout​

Ce qui transforme cette image en commande, c'est une fonction, dans son propre fichier, placée dans un dossier que votre shell charge au démarrage (l'organisation expliquée dans mon workflow ZSH modulaire). Elle monte le dossier courant dans le container, en lecture seule partout ailleurs, sans privilèges, et jetable après chaque 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}" "$@"?
}

Le code est identique pour zsh et bash ; seuls le dossier et le chargement diffèrent.

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

for fn_file in ~/.bash/fns/*.sh; do
  [[ -r "$fn_file" ]] && source "$fn_file"
done

Vérifiez que le shell connaît la fonction : type md-convert doit répondre md-convert is a shell function.

Si l'image manque, md-convert n'échoue pas sur une erreur Docker cryptique : il affiche la commande docker build exacte à lancer ou, quand ~/tools/markitdown/Dockerfile a disparu lui aussi, vous renvoie vers cet article.

Conclusion​

Grâce à Markitdown et à la fonction md-convert que nous venons de construire, convertir des documents bureautiques en Markdown propre devient simple, sûr et natif dans votre terminal.

Consultez le repository officiel pour la liste complète des formats supportés :

• PDF
• PowerPoint
• Word
• Excel
• Images (métadonnées EXIF et OCR)
• Audio (métadonnées EXIF et transcription vocale)
• HTML
• Formats texte (CSV, JSON, XML)
• Archives ZIP (parcours récursif du contenu)
• URL YouTube
• EPUB
• ... et plus encore !

Dans ce guide, nous avons délibérément compilé uniquement les extensions Word, Excel et PDF ([docx,xlsx,pdf]) pour garder notre image Docker légère et strictement cadrée. Vous pouvez bien sûr étendre les capacités de l'outil selon vos besoins. Ajustez simplement les extras du pip install dans ~/tools/markitdown/Dockerfile et reconstruisez votre image.

Référez-vous à la section Optional Dependencies de la documentation officielle pour explorer tout le potentiel de cet utilitaire.