# Exécuter Quarto Markdown dans Docker > Exécutez Quarto Markdown dans Docker pour générer facilement de la documentation et des slideshows. Apprenez à construire votre propre image Docker et à rendre du Markdown en PDF, HTML et Reveal.js. ---  **TL;DR** Cet article montre comment exécuter Quarto (un outil basé sur Pandoc qui convertit du Markdown en PDF, HTML, Word, ePub ou slideshows reveal.js) via Docker, soit en construisant une image personnalisée à partir d'un `Dockerfile`, soit en utilisant l'image prête à l'emploi `ghcr.io/quarto-dev/quarto`. Il détaille le rendu d'un même fichier Markdown en PDF, en HTML et en présentation reveal.js multi-slides avec `quarto render test.md --to `. [Quarto](https://quarto.org/) est un outil pour produire des PDF, des documents Word, des pages web HTML, des fichiers ePub, des slideshows et bien d'autres sorties encore à partir d'un fichier Markdown. Avec Quarto, vous pouvez transformer n'importe quel contenu markdown en un nouveau PDF par exemple. Quarto propose énormément de fonctionnalités, auxquelles s'ajoutent les extensions de sa communauté, ce qui en fait un outil vraiment pratique pour quiconque souhaite produire de la documentation. Personnellement, je n'ai plus utilisé de traitement de texte du genre Word depuis plusieurs années ; ni PowerPoint — je ne sais même plus quand c'était la dernière fois. Et pourtant, je produis beaucoup de documentation et de slideshows. J'écris tout en Markdown et je génère des PDF ou des slideshows depuis le même contenu. Jusqu'il y a peu, j'utilisais [pandoc](https://pandoc.org/) mais, après avoir pris le temps d'explorer Quarto, c'est nettement plus puissant. Comme toujours sur ce blog, vous n'allez pas installer Quarto à l'ancienne. Vous allez l'exécuter depuis une image Docker — et vous n'avez même pas besoin de construire cette image vous-même. ## Générez votre premier PDF, sans rien installer {#render-your-first-pdf-without-installing-anything} Créez un dossier temporaire (`mkdir -p /tmp/docker-quarto && cd $_`), déposez-y un fichier Markdown nommé `test.md` et lancez : ```bash $ docker run -it --rm -v .:/input -w /input -u $(id -u):$(id -g) ghcr.io/quarto-dev/quarto:latest quarto render test.md --to pdf ``` ```bash $ docker run -it --rm -v .:/input -w /input -u $(id -u):$(id -g) cavo789/quarto quarto render test.md --to pdf pandoc to: latex output-file: test.tex standalone: true pdf-engine: xelatex variables: graphics: true tables: true default-image-extension: pdf metadata documentclass: scrartcl classoption: - DIV=11 - numbers=noendperiod papersize: letter header-includes: - \KOMAoption\{captions}\{tableheading} block-headings: true Rendering PDF running xelatex - 1 This is XeTeX, Version 3.141592653-2.6-0.999996 (TeX Live 2024) (preloaded format=xelatex) restricted \write18 enabled. entering extended mode running xelatex - 2 This is XeTeX, Version 3.141592653-2.6-0.999996 (TeX Live 2024) (preloaded format=xelatex) restricted \write18 enabled. entering extended mode Output created: test.pdf ``` Un fichier `test.pdf` se trouve maintenant à côté de votre Markdown, vous en êtes le propriétaire, et il ressemble à ceci :  Cette image est l'image officielle de Quarto — rien à construire, rien d'installé sur votre machine, et le container se supprime tout seul dès que le rendu est terminé. > **Rappel sur la CLI Docker:** > > Pour rappel, les options de la commande Docker run utilisées sont (presque toujours les mêmes) : > > * `-it` pour démarrer Docker en mode interactif, ce qui permet au script exécuté dans le container de vous poser des questions par exemple, > * `--rm` pour demander à Docker de tuer et supprimer le container dès que le script a été exécuté (sinon vous vous retrouverez avec une longue liste de containers Docker arrêtés mais non supprimés ; vous pouvez le vérifier en n'utilisant pas le flag `--rm` puis en lançant `docker container list` dans la console), > * `-v .:/input` pour partager votre dossier courant avec un dossier appelé `/input` dans le container Docker, > * `-w /input` pour indiquer à Docker que le répertoire courant, dans le container, sera le dossier `/input`, > * `-u $(id -u):$(id -g)` demande à Docker de réutiliser vos identifiants locaux : ainsi, quand un fichier est modifié ou créé dans le container, il vous appartiendra, > * ensuite le nom de l'image Docker de Quarto, et, enfin, > * `quarto render test.md --to pdf` c'est-à-dire la ligne de commande à lancer dans le container. > **Masquer les informations non essentielles:** > > Ajoutez l'argument CLI `--log-level warning` à Quarto pour ne lui faire afficher que les avertissements (et les erreurs). La sortie non essentielle sera masquée et vous garderez une console propre. ## Le fichier source {#the-source-file} Voici le `test.md` utilisé ci-dessus : **/tmp/docker-quarto/test.md** ```markdown # What is Quarto? Explain like I'm five Imagine you want to write a story or a report, but instead of using a fancy computer program, you use plain text. That's kind of like Markdown, a simple language that lets you format your text without getting too complicated. Now, Quarto is like a super-powered writing tool that understands Markdown and can also help you write code in different languages, like R or Python. It's like having a helper in your writing process, making things easier and more fun. So, if you want to create documents, presentations, or even books, Quarto and Markdown can be your friends. They'll help you organize your thoughts, add cool features, and even share your work with the world. ``` **Référez-vous à la documentation officielle de [Quarto](https://quarto.org/) pour tout savoir en détail sur le Markdown qu'il accepte.** La seule chose qui change d'un format de sortie à l'autre, c'est l'argument `--to`. ## Le même fichier, en HTML et en slideshow {#the-same-file-as-html-and-as-a-slideshow} Modifiez simplement l'argument `--to` et remplacez `pdf` par `html` : `docker run -it --rm -v .:/input -w /input -u $(id -u):$(id -g) ghcr.io/quarto-dev/quarto:latest quarto render test.md --to html --log-level warning` Vous avez maintenant un fichier `test.html` dans votre répertoire. Pour un slideshow, l'argument `--to` doit valoir `revealjs` : `docker run -it --rm -v .:/input -w /input -u $(id -u):$(id -g) ghcr.io/quarto-dev/quarto:latest quarto render test.md --to revealjs --log-level warning` Ouvrez le fichier `test.html` et vous obtiendrez ceci :  Ok, vous n'avez qu'un seul slide pour l'instant. Réouvrez le fichier `test.md` et insérez des *sauts de slide*. Cela se fait avec la syntaxe `----` : **/tmp/docker-quarto/test.md** ```markdown # What is Quarto? Explain like I'm five Imagine you want to write a story or a report, but instead of using a fancy computer program, you use plain text. That's kind of like Markdown, a simple language that lets you format your text without getting too complicated. ---- Now, Quarto is like a super-powered writing tool that understands Markdown and can also help you write code in different languages, like R or Python. It's like having a helper in your writing process, making things easier and more fun. ---- So, if you want to create documents, presentations, or even books, Quarto and Markdown can be your friends. They'll help you organize your thoughts, add cool features, and even share your work with the world. ``` Relancez la commande `--to revealjs` pour régénérer le slideshow en tant que fichier `test.html`. > **Information:** > > Lancez simplement `docker run -d --name static-site -p 8080:80 -v .:/usr/local/apache2/htdocs/ httpd:alpine` puis rendez-vous sur `http://127.0.0.1:8080/test.html` pour voir votre slideshow. Votre slideshow comporte maintenant trois slides (appuyez sur `espace` ou sur les flèches pour naviguer) :    > **Déployez simplement votre slideshow en ligne:** > > Le plus sympa, c'est que votre slideshow est prêt à être déployé sur votre serveur distant. Copiez le fichier html et le dossier associé (dans notre cas ici, le fichier `test.html` et le dossier `test_files`) sur votre serveur FTP par exemple et votre site sera accessible publiquement. Pas mal, non ? ## Construire votre propre image (facultatif — passez si l'image officielle suffit) {#build-your-own-image-optional--skip-it-if-the-official-one-is-enough} Il existe un certain nombre d'images prêtes à l'emploi sur Internet pour répondre à vos besoins. Vous les trouverez sur . L'image dite `Tier 0` — celle utilisée ci-dessus, `ghcr.io/quarto-dev/quarto:latest` — convient pour générer des sorties html / revealjs. Vous voudrez votre propre image le jour où vous aurez besoin de quelque chose qu'elle ne fournit pas : un package LaTeX pour une mise en page PDF particulière, R ou Python pour des cellules de code exécutables, une police, une extension Quarto intégrée. Créez un nouveau fichier appelé `Dockerfile` (il n'y a pas d'extension) avec ce contenu : **Dockerfile** ```docker # cspell:disable # Version number of Quarto to download and use # See https://github.com/quarto-dev/quarto-cli/pkgs/container/quarto for existing versions ARG QUARTO_VERSION=1.10.18 ARG OS_USERNAME=quarto ARG UID=1000 ARG GID=1000 FROM ghcr.io/quarto-dev/quarto:${QUARTO_VERSION} # librsvg2-bin is to allow SVG conversion when rendering a PDF file # (will install the rsvg-view binary) RUN --mount=type=cache,target=/var/cache/apt,rw \ set -e -x && \ apt-get update -y \ && apt-get install -y --no-install-recommends \ ca-certificates \ git \ pandoc \ pandoc-citeproc \ curl \ gdebi-core \ librsvg2-bin \ && apt-get clean \ && rm -rf /var/lib/apt/lists/* USER root # The input folder will be the one where we'll put our files before the conversion. # We should do this as root since it's a folder under / RUN set -e -x && \ mkdir -p /input # Should be done for the user; won't work if done for root # (quarto will say that "tinytex is not installed") ARG OS_USERNAME ARG UID ARG GID RUN set -e -x && \ groupadd -g ${GID} -o "${OS_USERNAME}" && \ useradd -l -m -u ${UID} -g ${GID} -o -s /bin/bash "${OS_USERNAME}" USER "${OS_USERNAME}" WORKDIR / # Install tools like tinytex to allow conversion to PDF RUN set -e -x && \ quarto install tool tinytex --update-path && \ ~/.TinyTeX/bin/x86_64-linux/tlmgr update --self --all && \ ~/.TinyTeX/bin/x86_64-linux/fmtutil-sys --all && \ # See https://github.com/rstudio/tinytex/issues/426 for explanation # Run tlmgr install for a few tinyText packages (needed for PDF conversion) ~/.TinyTeX/bin/x86_64-linux/tlmgr install fvextra footnotebackref pagecolor sourcesanspro sourcecodepro titling ``` Ceci fait, lancez `docker build -t cavo789/quarto .` et après environ trois minutes la première fois, vous obtiendrez votre propre image Docker : ```bash $ docker build -t cavo789/quarto . [+] Building 183.3s (9/9) FINISHED docker:default => [internal] load build definition from Dockerfile 0.1s => => transferring dockerfile: 1.80kB 0.0s => [internal] load metadata for ghcr.io/quarto-dev/quarto:1.6.36 0.7s => [internal] load .dockerignore 0.0s => => transferring context: 2B 0.0s => [stage-0 1/6] FROM ghcr.io/quarto-dev/quarto:1.6.36@sha256:7c800f23602e532de8d2e35de8 19.6s => => resolve ghcr.io/quarto-dev/quarto:1.6.36@sha256:7c800f23602e532de8d2e35de838e9f5331 0.0s => => sha256:7c800f23602e532de8d2e35de838e9f53310af381daa34cf3d733c05fd7dec72 955B / 955B 0.0s => => sha256:a9220a0c1eb7e69d971f705b026870f03e511a0c6a95ae0d1140d45089c2 1.73kB / 1.73kB 0.0s => => sha256:7478e0ac0f23f94b2f27848fbcdf804a670fbf8d4bab26df842d40a10c 30.44MB / 30.44MB 3.2s => => sha256:14a397168681603ca2ef7ec883ab375f79cc39ed6abfc602de3d16d 126.00MB / 126.00MB 13.0s => => sha256:682f5bc1f33ef91c217708dbd0f9c287f896d05632b47cdeb1ced02 130.07MB / 130.07MB 16.1s => => extracting sha256:7478e0ac0f23f94b2f27848fbcdf804a670fbf8d4bab26df842d40a10cd33059 1.8s => => extracting sha256:14a397168681603ca2ef7ec883ab375f79cc39ed6abfc602de3d16dc40197b37 0.7s => => extracting sha256:682f5bc1f33ef91c217708dbd0f9c287f896d05632b47cdeb1ced02166e3aa8d 3.2s => [stage-0 2/6] RUN --mount=type=cache,target=/var/cache/apt,rw set -e -x && ap 79.5s => [stage-0 3/6] RUN set -e -x && mkdir -p /input 0.4s => [stage-0 4/6] RUN set -e -x && groupadd -g 1000 -o "quarto" && useradd -l -m - 0.6s => [stage-0 5/6] RUN set -e -x && quarto install tool tinytex --update-path && ~ 80.4s => exporting to image 1.9s => => exporting layers 1.9s => => writing image sha256:f7222fdd5856beb8fb209a609fc9271a0f8f3a586449bc5d90a6b338e54453 0.0s => => naming to docker.io/cavo789/quarto 0.0s ``` > **Choisissez votre propre nom:** > > L'instruction précédente `docker build -t cavo789/quarto .` a créé une image appelée `cavo789/quarto`. Vous pouvez évidemment choisir un autre nom sans le moindre impact sur l'image. À partir de là, toutes les commandes de cet article fonctionnent de la même façon : remplacez juste `ghcr.io/quarto-dev/quarto:latest` par `cavo789/quarto`. Vous pouvez vérifier rapidement la taille de votre image ; elle est plutôt énorme mais, sauf si vous êtes vraiment à court de mémoire ou d'espace disque, ce n'est pas un problème. ```bash $ docker image list | grep quarto cavo789/quarto latest fe1d20bd71a6 1 minute ago 1.55GB ``` ## Pour aller plus loin {#going-further} Un seul fichier Markdown, trois valeurs de `--to`, trois livrables complètement différents — et pas une seule application installée sur votre machine. C'est ce que je trouve encore remarquable : la source de mon PDF, de ma page web et de mon slideshow est le même fichier texte, donc ils ne peuvent jamais diverger. Une fois à l'aise avec Quarto dans un simple container Docker, deux étapes suivantes s'imposent naturellement : transformer cette configuration en un vrai [devcontainer](/blog/quarto-devcontainer) VSCode (vous ouvrez le projet, tout est préinstallé et le hot-reload fonctionne directement), et parcourir [mes extensions Quarto préférées](/blog/quarto-extensions) pour enrichir votre documentation. Pour le volet slideshow en profondeur, voyez [Level Up Your Presentations with Quarto, reveal.js, Decktape, Docker and DevContainers](/blog/running-revealjs-with-docker).