<!--
  canonical-url: https://www.avonture.be/fr/blog/markitdown
  published:     2026-05-04
  This is a static plain-Markdown mirror generated at build time.
  Visit the canonical URL above for the fully rendered page, with images and interactive components.
-->

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

> Convertissez facilement vos documents MS Office (Word, Excel) et vos PDF en Markdown avec l'outil Markitdown de Microsoft. Avec les instructions pas à pas pour l'installer via Docker.

---
![Markitdown - Convertir des fichiers et des documents MS Office en Markdown](/img/v2/markdown.webp)

**TL;DR**Cet article explore l'utilisation de Markitdown, l'utilitaire de Microsoft très performant pour convertir des fichiers comme des documents Word, des feuilles Excel ou des PDF en Markdown propre. Pour garder votre système local sain et éviter de gérer des dépendances Python globales, l'auteur propose un guide pas à pas pour installer l'outil dans un container Docker isolé et léger. Le tutoriel couvre la création d'un Dockerfile personnalisé et d'une fonction shell `md-convert`, pour zsh ou bash. Avec ce montage, vous lancez vos conversions depuis n'importe quel dossier, directement dans votre terminal, en toute sécurité.

Récemment, un ami m'a parlé d'un outil de Microsoft appelé [Markitdown](https://github.com/microsoft/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.

> **Besoin seulement d'une plage Excel ou d'un fichier CSV en tableau Markdown ?:**
>
> Markitdown est un outil généraliste, donc lourd. Si votre besoin est plus étroit — transformer une plage Excel copiée ou un fichier CSV en tableau Markdown — mes outils en ligne [XLS2MD](/blog/markdown-xls2md) et [CSV2MD](/blog/markdown-csv2md) vont plus vite, sans Docker.

## Première conversion {#first-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 :

```bash
$ 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 {#why-this-approach}

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.

> **J'adore Docker aussi pour ça:**
>
> C'est exactement pour ça que Docker est indispensable : l'isolation complète. Tout tourne dans le container. Une fois mes expérimentations terminées, je supprime l'image et il ne reste rien sur mon disque, à part le Dockerfile nécessaire pour la recréer à la demande. *Si ce raisonnement est nouveau pour vous, [Docker - Explain me like I'm five - What's Docker for?](/blog/docker-definition-like-im-five) l'explique avec une analogie culinaire.*

## Installation {#installation}

### Créer notre image Docker {#create-our-docker-image}

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) :

**Project: \~/tools/markitdown**

> **Note:**
>
> Lancez maintenant 'docker build -t markitdown \~/tools/markitdown' pour créer l'image Docker.

**Dockerfile**

```docker
# syntax=docker/dockerfile:1.7-labs

FROM python:3.14-slim AS builder

# Prevent Python from writing .pyc files, buffer logs, and skip pip update checks
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1

WORKDIR /app

# Install required dependencies for docx, xlsx, and pdf parsing to an isolated prefix
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install --prefix=/python "markitdown[docx,xlsx,pdf]==0.1.7"

FROM python:3.14-slim AS final

# Enforce read-only compatibility and link the isolated Python environment
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    HOME=/tmp \
    PYTHONPATH=/python/lib/python3.14/site-packages \
    PATH="/python/bin:$PATH"

ARG UID=1000
ARG GID=1000

# Create an unprivileged user without a valid login shell for strict security
RUN groupadd -g "${GID}" developer && \
    useradd -m -u "${UID}" -g "${GID}" -s /usr/sbin/nologin developer

COPY --from=builder /python  /python

WORKDIR /workspace

USER developer

# Execute the CLI tool directly
ENTRYPOINT ["python", "-m", "markitdown"]
```

> **Extensions supportées:**
>
> Regardez la ligne `pip install --prefix=/python "markitdown[docx,xlsx,pdf]==0.1.7"` dans notre `Dockerfile` ; nous pourrions remplacer `docx,xlsx,pdf` par `all` pour pouvoir convertir toutes les extensions supportées par Markitdown, mais notre image Docker finale serait plus volumineuse.
>
> Ou alors, ajoutez simplement les extensions dont vous avez besoin. Référez-vous à la documentation officielle pour ça.

Construisez-la :

```bash
docker build -t markitdown ~/tools/markitdown
```

### Rendre `md-convert` disponible partout {#make-md-convert-available-everywhere}

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](/blog/modular-zsh-workflow)). Elle monte le **dossier courant** dans le container, en lecture seule partout ailleurs, sans privilèges, et jetable après chaque conversion :

**md-convert.sh**

```bash
# 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.

**1. Créez le fichier** dans `~/.zsh/fns/` :

**Project: \~/.zsh/fns**

**md-convert.zsh**

```bash
# 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}" "$@"
}
```

**2. Chargez le dossier depuis `~/.zshrc`.** C'est déjà fait si vous avez suivi un de mes articles « Ollama au quotidien ». Sinon, ajoutez ceci à la fin de `~/.zshrc` :

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

**3. Ouvrez un nouveau terminal** (ou lancez `exec zsh`).

**1. Créez le fichier** dans `~/.bash/fns/` :

**Project: \~/.bash/fns**

**md-convert.sh**

```bash
# 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}" "$@"
}
```

**2. Chargez le dossier depuis `~/.bashrc`.** Ajoutez ceci à la fin de `~/.bashrc` (le test `-r` évite une erreur si le dossier est vide) :

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

**3. Ouvrez un nouveau terminal** (ou lancez `exec bash`).

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.

> **Vous venez de la version précédente de cet article ?:**
>
> Elle installait `md-convert` comme script dans `/usr/local/bin/`. Supprimez-le (`sudo rm /usr/local/bin/md-convert`) : la fonction prend le relais, et l'ancien script traînerait sinon sur votre disque.

## Conclusion {#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](https://github.com/microsoft/markitdown/) 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](https://github.com/microsoft/markitdown/#optional-dependencies) de la documentation officielle pour explorer tout le potentiel de cet utilitaire.

> **PDF complexes, tableaux denses, pages scannées ?:**
>
> Markitdown analyse chaque format avec une librairie dédiée : c'est rapide et léger, mais ça aplatit parfois une mise en page complexe. Quand le document compte vraiment, je passe maintenant à une seconde image, plus lourde, construite exactement de la même façon : voir [Docling - Convert PDF, Word, PowerPoint, Excel and HTML to Markdown, GPU-Accelerated](/blog/docling), qui utilise de vrais modèles de mise en page et de structure de tableaux (sur le GPU, si vous en avez un).