Exécuter Quarto Markdown dans Docker

Quarto 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 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​

Créez un dossier temporaire (mkdir -p /tmp/docker-quarto && cd $_), déposez-y un fichier Markdown nommé test.md et lancez :

$ 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▋

$ 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é.

Le fichier source​

Voici le test.md utilisé ci-dessus :

# 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 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​

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

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

Votre slideshow comporte maintenant trois slides (appuyez sur espace ou sur les flèches pour naviguer) :

Construire votre propre image (facultatif — passez si l'image officielle suffit)​

Il existe un certain nombre d'images prêtes à l'emploi sur Internet pour répondre à vos besoins. Vous les trouverez sur https://gitlab.com/quarto-forge/docker. 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 :

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

$ 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
▋

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

$ docker image list | grep quarto
cavo789/quarto  latest  fe1d20bd71a6  1 minute ago  1.55GB▋

Pour aller plus loin​

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 VSCode (vous ouvrez le projet, tout est préinstallé et le hot-reload fonctionne directement), et parcourir mes extensions Quarto préférées pour enrichir votre documentation. Pour le volet slideshow en profondeur, voyez Améliorez vos présentations avec Quarto, reveal.js, Decktape, Docker et les DevContainers.