Obtenir une mindmap plus attrayante avec Markmap et Quarto

En 2023, j'ai écrit cet article Créer une mind map avec Docker et Markdown sur la façon de rendre un document Markdown sous forme de mindmap.

Cette fois, j'aimerais aller un cran plus loin et rendre le tout plus attrayant.

Deux autres façons de transformer du texte en diagramme sur ce blog : générer du Mermaid depuis un script Python et afficher un fichier JSON sous forme de mindmap.

Voici où nous allons — la même liste Markdown toute simple, rendue en mindmap HTML autonome et soignée avec Quarto :

Commençons par le commencement : lancez VSCode et créez un nouveau fichier. Comme nous allons faire un peu plus que ça, créons un nouveau dossier : mkdir -p /tmp/markmap && cd $_.

Créez-y un fichier Markdown, par exemple overview.qmd. L'extension .qmd sert juste à dire ceci est un fichier Markdown et nous comptons l'utiliser avec Quarto ; rien de spécial ici.

# 📚 Project Overview

## 🚀 Goals

- ✅ **Launch MVP**
- 🌱 Collect ==user feedback==?
- 📈 Iterate every 2 weeks

## 🧰 Tech Stack

- `Next.js` + `Tailwind`?
- 🧠 AI via OpenAI

- 🐘 PostgreSQL DB

## 🔁 Feedback Loop

- 📞 Customer interviews
- 📝 Surveys
- 📊 Usage metrics

## 📅 Timeline

- Q1 → Prototyping
- Q2 → MVP 🚢?
- Q3 → Growth 📈

Nous obtenons donc ceci :

Afficher la markmap en ligne​

Rendez-vous sur https://markmap.js.org/repl et collez le contenu Markdown pour obtenir immédiatement un premier rendu :

Ok, ça marche mais ce n'est pas vraiment impressionnant.

Installer l'extension VSCode​

Il existe une extension Markmap sur le marketplace ; rendez-vous sur https://marketplace.visualstudio.com/items?itemName=gera2ld.markmap-vscode pour l'installer.

Une fois installée dans VSCode, appuyez sur CTRL+SHIFT+P pour ouvrir la Command Palette, cherchez Markmap, sélectionnez Markmap: open as markmap et appuyez sur Enter.

Vous obtiendrez quasiment la même sortie que la version en ligne :

Configurer le rendu​

En créant un fichier .vscode/settings.json, vous pouvez définir du CSS et des options par défaut, c'est-à-dire configurer l'extension Markmap-vscode.

Créez le fichier .vscode/settings.json avec ce contenu :

{
    "markmap.customCSS": ".markmap-link,\nline {\n\tstroke: #505050;\n\tstroke-width: 1.5px;\n}\n.markmap-node > circle {\n\tstroke: #202020;\n\tstroke-width: 1.5px;\n\tr: 6px;\n\tfill: #242424;\n}\n\n.markmap-foreign a {\n\ttext-decoration: none;\n\tcolor: #bbbbbb !important;\n}\n\n.markmap-highlight rect {\n\t/* fill: #303030 !important; */\n\tfill: transparent !important;\n\ttransform: scale(0.84, 0.7) !important;\n\ttransform-origin: center !important;\n\ttransform-box: fill-box;\n\ttransform-origin: center;\n}",?
    "markmap.defaultOptions": "{\n  \"color\": \"function(d, i) { return d3.interpolateRainbow(i / 10); }\",\n  \"nodeFont\": \"20px 'Segoe UI', 'Helvetica Neue', sans-serif\",\n  \"spacingVertical\": 40,\n  \"spacingHorizontal\": 140,\n  \"initialExpandLevel\": -1,\n  \"duration\": 1000,\n  \"paddingX\": 10,\n  \"paddingY\": 10\n}"?
}

Sauvez le fichier, retournez dans overview.qmd et, si nécessaire, relancez Markmap: open as markmap.

L'aperçu sera bien meilleur :

Générer une page HTML avec Quarto​

Dernière étape de cet article : rendons notre contenu Markdown sous forme d'une jolie page HTML, grâce à Quarto.

Créons un nouveau fichier render.sh avec le contenu suivant :

#!/usr/bin/env bash
set -euo pipefail?

mkdir -p .build/.quarto_deno_cache_data/deno?
chmod -R 777 .build/.quarto_deno_cache_data?

# shellcheck disable=SC2046 # id -u/-g never contain whitespace, safe unquoted
docker run -it --rm \
  -u $(id -u):$(id -g) \?
  -v ".:/public" \?
  -w /public \?
  -v "./.build/.quarto_deno_cache_data:/container_cache" \?
  -e DENO_DIR="/container_cache/deno" \
  -e QUARTO_CACHE_DIR="/container_cache/quarto" \
  -e HOME="/public" \
  ghcr.io/quarto-dev/quarto \
  quarto render overview.qmd --no-cache --output-dir .build --quiet

( cd .build && explorer.exe overview.html )?

Rendez ce fichier exécutable en lançant chmod +x render.sh.

Il est temps de l'appeler : dans votre console, lancez ./render.sh pour exécuter le script.

La toute première fois, ce sera plus long car Docker doit télécharger l'image Docker de Quarto (ghcr.io/quarto-dev/quarto).

Le script va appeler Quarto, faire quelques initialisations et convertir le fichier overview.qmd en une page HTML qui sera stockée dans un nouveau dossier .build.

Après avoir lancé le script, vous aurez donc cette structure dans votre projet :

Le plus chouette : Quarto a rendu votre contenu Markdown sous forme d'une belle page — le même résultat déjà montré en haut de cet article, ce qui était l'objectif de ce billet.

Conclusion​

Il est très simple d'écrire une structure de type MindMap et de générer soit une image, soit une page web. On pourrait aller encore plus loin avec Quarto, car une page web peut être personnalisée avec du CSS.

Et, comme c'est une page web, vous pouvez facilement copier-coller le rendu dans un e-mail, un document Word ou n'importe quoi d'autre et obtenir un visuel plutôt sympa pour ce qui n'était au départ qu'une simple liste.