Rendez votre projet Quarto prêt pour les Devcontainers — fini les galères de configuration

J'adore utiliser Quarto et j'ai des tonnes de projets de documentation sur mon disque. J'écris de la documentation utilisateur, de la documentation développeur et aussi des guides d'installation pour quasiment chaque projet que je code.

Si vous n'avez jamais lancé Quarto via Docker, Exécuter Quarto Markdown dans Docker est un bon point de départ ; cet article part de cette idée pour vous offrir un devcontainer VSCode complet.

L'idée m'est vite venue de créer une image Docker pour pouvoir développer ma documentation tranquillement, ainsi qu'une configuration devcontainer pour VSCode. Maintenant, quand je veux écrire ma documentation, en moins d'une minute, je peux créer un environnement entièrement dédié à la rédaction de documentation.

Entre autres, j'installe Quarto, j'installe et configure plusieurs extensions pour VSCode, et je lance Quarto en mode preview : dès que j'enregistre une modification, Quarto régénère la documentation tout seul.

Voyons comment faire ; vous allez voir, c'est vraiment simple.

Le même devcontainer, spécialisé pour les diaporamas, est utilisé dans Améliorez vos présentations avec Quarto, reveal.js, Decktape, Docker et les DevContainers ; et poussé à l'échelle industrielle dans Quarto - Comment j'ai construit un écosystème auto-documenté pour plus de 50 projets.

Commençons par un projet Quarto simple​

Bien sûr, si vous en avez déjà un, allez directement dans votre projet. Ici, pour ce billet, nous allons simplement réutiliser un projet existant.

En lançant les commandes ci-dessous dans une console, vous téléchargerez uniquement le dossier brand du projet quarto-examples :

$ cd /tmp
git clone --filter=blob:none --sparse https://github.com/quarto-dev/quarto-examples
cd quarto-examples
git sparse-checkout set brand
cd brand/brand-simple
▋

Lancez code . pour ouvrir le projet dans VSCode et vous obtiendrez ceci :

Voici où nous allons : ouvrir ce même projet comme devcontainer, lancer quarto preview ., et le site tourne déjà — sans aucune installation de Quarto sur votre host.

Ridiculement simple, non ? Construisons ça, en commençant par trois fichiers.

Nous allons devoir créer trois fichiers​

Pour obtenir les meilleures performances en termes de vitesse de build de l'image Docker et d'utilisation du mécanisme de cache de Docker, nous allons devoir créer trois fichiers :

Le fichier .devcontainer/compose.yaml est nécessaire pour dire à VSCode de créer notre image Docker si elle n'existe pas encore, ou de la réutiliser si elle existe. Ce fichier est donc essentiel côté performances.

Le fichier .devcontainer/Dockerfile définit notre image Docker : les binaires dont nous avons besoin, la configuration utilisateur, etc.

Le fichier .devcontainer/devcontainer.json est utilisé par VSCode pour comprendre et construire notre environnement de travail.

Informations supplémentaires (optionnel — passez si les valeurs par défaut vous conviennent)​

Installation de sudo​

Pendant la création de l'image Docker, nous installons aussi la commande sudo et autorisons notre utilisateur vscode à lancer sudo su root dans le devcontainer sans devoir saisir de mot de passe. La raison : parfois, Quarto se plaint d'une dépendance manquante (par exemple lors d'un export en PDF, quand une librairie manque). Pour permettre au développeur d'ajouter rapidement la dépendance et de faire quelques tests sans devoir reconstruire le container encore et encore, sudo est installé.

Arguments de build (optionnel — ne lisez que ceux qui vous concernent)​

Installation de Chromium​

Si vous regardez le fichier .devcontainer/compose.yaml, vous verrez un argument appelé INSTALL_CHROMIUM. Selon votre projet, vous en aurez besoin ou pas.

En effet, dans certaines situations, lors du rendu de votre documentation en Word (c'est-à-dire en lançant par exemple quarto render . --profile docx --to docx), Quarto peut vous demander d'installer Chromium. Pour éviter de le faire chaque fois, ouvrez simplement le fichier .devcontainer/devcontainer.json, cherchez INSTALL_CHROMIUM et mettez-le à true.

Note : si vous modifiez le code du .devcontainer/Dockerfile ou le fichier .devcontainer/devcontainer.json, vous devrez reconstruire le container comme expliqué ci-dessous.

Installation de Code Spell Checker​

De la même manière, vous avez une variable appelée INSTALL_CSPELL. Mettez-la à true si vous voulez installer l'outil Code-spell check (nécessite Node.js).

Installation de GraphViz​

De la même manière, vous avez une variable appelée INSTALL_GRAPHVIZ. Mettez-la à true si vous voulez installer le convertisseur GraphViz.

C'est nécessaire quand, dans votre fichier .qmd, vous avez un graphe comme celui-ci :

digraph flow {
  rankdir = LR;

  A [shape=box, label="Source"];
  B [shape=ellipse, label="Processor"];
  C [shape=box, label="Destination"];

  A -> B;
  B -> C;
}

Installation des pre-commit-hooks​

La troisième variable est INSTALL_PRECOMMIT_HOOKS et, si votre documentation a son propre dossier .git, ce sera une bonne idée de mettre la variable à true : ainsi, lors du commit de vos modifications, quelques contrôles de qualité des données et outils de formatage seront appliqués.

Ouvrir notre projet comme Devcontainer​

Maintenant, appuyez juste sur F1 (ou CTRL+SHIFT+P) et sélectionnez Dev Containers: Rebuild and Reopen in Container. Si vous n'avez pas cette commande, vérifiez que l'extension ms-vscode-remote.remote-containers de Microsoft est bien installée.

Donc, une fois la commande Dev Containers: Rebuild and Reopen in Container lancée, VSCode fermera votre session courante et en ouvrira une nouvelle. La toute première fois, VSCode devra faire quelques initialisations (comme construire l'image Docker et télécharger les extensions, ce sera donc plus lent).

Après quelques secondes, vous obtiendrez un écran comme celui-ci :

1. En bas à gauche, dans la barre de statut, vous avez le texte "Dev Container: xxx" (suivi du nom de notre container tel que configuré dans le fichier devcontainer.json).
2. Dans la fenêtre Terminal (si vous ne la voyez pas, appuyez sur CTRL+ù), vous verrez un pense-bête avec les commandes principales, comme quarto preview . pour lancer le site avec le hot reload.

Donc, toujours dans le Terminal, tapez quarto preview . puis appuyez sur Enter — vous obtiendrez la même sortie que celle déjà montrée en haut de cet article.

En théorie, votre navigateur sera lancé automatiquement et le site ouvert, affichant le même résultat que celui déjà montré plus haut. Sinon, suivez simplement le lien en appuyant sur ALT et en cliquant dessus.

Ridiculement simple, non ?

Qu'avons-nous fait ?​

À ce stade, qu'avons-nous fait ? Nous avons récupéré un projet de site Quarto et nous nous sommes assurés de le « dockeriser ».

Regardons le fichier _quarto.yml du projet que nous venons de cloner (vous trouverez plus d'informations sur le site officiel de Quarto : Creating a website) :

project:?
  type: website

website:?
  title: "Simple Brand Example"
  navbar:
    title: "Demo CO"
    tools:?
      - icon: github?
        href: https://github.com/quarto-dev/quarto-examples/tree/main/brand/brand-simple

Nous avons ajouté trois fichiers au projet, dans un dossier spécial appelé .devcontainer. Ce dossier indique à VSCode que nous souhaitons utiliser un container Docker quand nous travaillons sur ce projet. Le container sera basé sur une image Docker personnalisée (telle que codée dans .devcontainer/Dockerfile). L'image réutilisera l'image officielle de Quarto.

Ainsi, sans devoir installer Quarto sur notre machine, nous pourrons utiliser toutes les fonctionnalités de Quarto.

Enfin, nous devons basculer vers le devcontainer : juste après avoir ouvert VSCode, nous devons lancer une commande spéciale pour rouvrir le projet comme devcontainer.

Cette commande est, la première fois, Dev Containers: Rebuild and Reopen in Container mais, dès que l'image personnalisée a été créée une fois, nous pouvons simplement utiliser Dev Containers: Reopen in Container.

Rédiger notre documentation​

Jusqu'ici, nous avons déjà lancé quarto preview . dans un terminal. La documentation a été générée et notre site est déjà affiché (sur http://localhost:7519 ou tout autre port).

Testons le hot reload : éditez le fichier index.qmd que vous trouverez dans le dossier racine et changez quelque chose. Par exemple, remplacez le mot Overview par Preface et enregistrez.

Comme vous le voyez sur l'image ci-dessus, il me suffit de faire une modification, d'enregistrer mon fichier et d'attendre moins d'une seconde pour que le site soit mis à jour automatiquement. Rien à faire (je n'ai pas besoin de rafraîchir la page). Simple, non ?

Utiliser le terminal​

Allez dans la fenêtre Terminal (si vous ne la voyez pas, appuyez sur CTRL+ù).

Regardez maintenant la partie droite : il y a un terminal Configuring... mais aussi un bash workspace (le nom de notre projet). Si vous ne le voyez pas, regardez juste au-dessus de Configuring... et cliquez sur le bouton +.

Comme vous le voyez, vous avez quelques instructions. Ces instructions ont été codées dans la dernière partie du fichier .devcontainer/Dockerfile. Elles sont là juste pour aider l'utilisateur la première fois.

Donc, si votre objectif est de générer la documentation finale, vous pouvez toujours vous dire Ah oui, il me suffit de lancer quarto render .

Qu'est-ce que pre-commit ?​

Dans ce projet, j'ai prévu l'installation de pre-commit. C'est un outil optionnel qui lancera quelques contrôles sur votre projet avant que vous ne le poussiez vers votre système de versioning (comme GitHub ou GitLab). Je lui ai consacré un article complet : Git - pre-commit-hooks.

En ajoutant pre-commit dans le devcontainer, vous aurez le privilège de ne plus jamais commiter de fichiers avec des défauts comme, par exemple, des problèmes de formatage dans votre contenu Markdown.

Si cette idée vous plaît, créez le fichier .pre-commit-config.yaml dans le dossier racine de votre projet (donc pas dans le dossier .devcontainer mais dans son dossier parent).

Copiez/collez simplement le contenu ci-dessous :

# Pre-commit configuration for Quarto projects
exclude: "^.build/|^.git/|^.quarto/"?

repos:
  # --- Universal hooks for clean files ---
  - repo: https://github.com/pre-commit/pre-commit-hooks?
    rev: v6.0.0
    hooks:
      - id: check-added-large-files
      - id: check-case-conflict
      - id: check-json
      - id: check-merge-conflict
      - id: check-yaml
      - id: detect-private-key
      - id: end-of-file-fixer
      - id: trailing-whitespace

  # Markdown linter
  - repo: https://github.com/igorshubovych/markdownlint-cli
    rev: v0.45.0
    hooks:
      - id: markdownlint
        args:?
          - "--config=.config/.markdownlint.yaml"

  # Checks all of the hyperlinks in a markdown text to determine if they are alive or dead
  - repo: https://github.com/tcort/markdown-link-check
    rev: v3.13.7
    hooks:
      - id: markdown-link-check
        name: Check Markdown Links
        entry: markdown-link-check
        language: node
        types: [markdown]

  # The hook below hook extracts the YAML front matter from each .qmd
  # file and validates its syntax using yq.
  # It helps catch formatting errors (e.g. missing colons, invalid keys)
  # before committing.
  # Only the YAML block between the first pair of --- lines is checked.
  - repo: local?
    hooks:
      - id: validate-qmd-yaml
        name: Validate YAML front matter in .qmd
        entry: bash -c 'awk "/^---/{f=!f;next}f" "$1" | yq eval "." - > /dev/null'?
        language: system
        pass_filenames: true
        args: ["{}"]?
        files: \.qmd$?

  # --- Spelling ---
  # Requires to install cspell in the Docker file as a binary. This implies to install NPM tool
  # The .vscode/cspell.json file is shared with VSCode
  - repo: local
    hooks:
      - id: cspell
        name: Spell check with cspell
        entry: cspell
        language: system
        args:
          - "--config=.vscode/cspell.json"
          - "--no-progress"
          - "--no-summary"
        exclude: ^.*_extensions/.*?

Une fois ce fichier en place, quand vous lancerez la commande git commit depuis le terminal (CTRL+ù), git lancera d'abord pre-commit pour exécuter les hooks. Dans le fichier .pre-commit-config.yaml ci-dessus, nous avons défini deux hooks : le premier pour faire des vérifications génériques sur les fichiers, puis un second pour s'assurer qu'il n'y a pas d'erreurs de linting dans les fichiers .md (consultez le repo officiel pour plus d'infos).

Ces hooks sont déclenchés chaque fois que vous commitez des fichiers (et uniquement sur les fichiers commités ; pas sur tout le projet).

Vous pouvez aussi forcer l'exécution des hooks sans commiter, en lançant pre-commit run --all-files dans la console.

Cette commande vérifiera tous les fichiers.

pre-commit est un outil précieux pour garantir le respect des standards de qualité établis dans l'industrie.

Conclusion​

Avec seulement trois fichiers (.devcontainer/compose.yaml, .devcontainer/Dockerfile et .devcontainer/devcontainer.json), nous avons converti un projet simple en Devcontainer où Quarto est préinstallé, les extensions installées et configurées, et où des fonctionnalités comme la prévisualisation automatique tournent.

Cool, non ?