tjst-t/boxloom

Boxloom : rédiger des présentations

Boxloom sépare le fond de la forme. Vous écrivez uniquement ce qu'est le contenu (une liste de points, une comparaison d'options, un plan daté). Le modèle décide de chaque couleur, taille de police, marge et position. Vous n'écrivez jamais de couleur, de taille ou de coordonnée en dehors de la seule échappatoire (shapes, en dernier recours).

La boucle est toujours :

1. boxloom schema — lisez ce que les modèles actuels acceptent (faites ceci en premier).
2. Écrivez deck.bx.md.
3. boxloom check -format json deck.bx.md — corrigez chaque erreur, puis chaque avertissement que vous pouvez.
4. Répétez l'étape 3 jusqu'à obtenir "ok": true et aucun avertissement layout-overflow.
5. boxloom build -o deck.pptx deck.bx.md (les flags avant le fichier).

Les commandes s'exécutent depuis le répertoire boxloom/ du dépôt : go run ./cmd/boxloom <schema|check|build|parse> … (Go 1.24+, aucune autre dépendance).

1. Lisez d'abord le schéma

boxloom schema [-template light|dark] affiche un document JSON. C'est la source de vérité ; si ce fichier et le schéma sont en désaccord, le schéma prévaut.

• markdown.rules — les règles de syntaxe (liste courte ; obéissez à toutes).
• markdown.frontMatter — les clés autorisées dans l'en-tête --- (title est obligatoire).
• templates[].blocks — les blocs à délimitation (:::name) que ce modèle connaît, avec inside (où il peut apparaître), contains (ce qu'il contient) et minChildren.
• templates[].subsystems — les types de figures (blocs de code ```name), avec markdown (leurs règles supplémentaires) et schema (un pointeur JSON vers irSchema donnant toutes les clés autorisées).
• Tout ce qui n'est pas listé est une erreur. N'inventez pas de noms de blocs, d'attributs ou de clés.
• Les modèles sont choisis par leur nom (template: light dans l'en-tête, ou -template dark). Un modèle personnalisé est un fichier de table de valeurs passé par chemin : -template ./my.json (fonctionne pour schema, check, build, fonts ; exemple examples/templates/forest.json). Lorsque la présentation sera construite avec un modèle personnalisé, exécutez schema et check avec le même -template — les noms de rôles et les styles de texte proviennent de ce fichier.
• variant (# Titre {variant=…}) existe dans la syntaxe, mais les modèles actuels ne déclarent aucune variante (templates[].variants est vide), donc ne l'utilisez pas.

La sortie est volumineuse. Pour voir uniquement ce dont vous avez besoin :

go run ./cmd/boxloom schema -template light > /tmp/schema.json
python3 -c "import json;d=json.load(open('/tmp/schema.json'));print(json.dumps({'rules':d['markdown']['rules'],'blocks':d['templates'][0]['blocks'],'subsystems':[(x['name'],x['markdown']) for x in d['templates'][0]['subsystems']]},ensure_ascii=False,indent=1))"
python3 -c "import json;d=json.load(open('/tmp/schema.json'));print(json.dumps(d['irSchema']['$defs']['gantt'],ensure_ascii=False,indent=1))"   # toutes les clés gantt

2. Syntaxe en un écran

---
title: Migration du service de reporting vers le nouveau cluster
subtitle: Plan et options (exemple fictif)
author: Équipe plateforme
date: 2026-11-11
confidential: Interne
disclaimer: Tous les noms et chiffres sont fictifs
template: light
---

# Support du fournisseur pour l'ancien cluster

:::lead
L'ancien cluster perd le support du fournisseur en mars 2028, les 14 services qui y sont hébergés doivent donc déménager avant cette date.
:::

- Le fournisseur arrête les correctifs de sécurité le **2028-03-31**
- 14 services y tournent encore ; 9 peuvent être déplacés sans modification de code
- Le déplacement prend environ 6 semaines par groupe de services

:::source
Avis de support du fournisseur de 2026-09 ; inventaire des services en octobre 2026
:::

:::notes
Notes de l'orateur ici. Uniquement des paragraphes simples et des puces.
:::

• # Titre commence une diapositive. Gardez le titre court, une accroche qui tient sur une ligne ("Support du fournisseur pour l'ancien cluster") ; un titre qui dépasse génère un avertissement (title-wrap). Écrivez ce que la diapositive dit — la conclusion — sous forme de phrase dans :::lead juste après le titre (1–2 lignes). Le modèle place le lead sous le titre, en dehors du corps.

• --- n'est pas un séparateur de diapositive (c'est une erreur). ## et les titres plus profonds sont des erreurs (un titre de groupe s'écrit :::column Titre, pas comme un sous-titre).

• Corps : paragraphes, puces - / 1. (deux niveaux maximum), **emphase** (un seul type d'emphase), `code`, [texte](url), \ final pour un saut de ligne significatif. Pas d'italique, de barré, de notes de bas de page, de HTML.

• Blocs à délimitation : ouverts par :::nom et fermés avec le même nombre de deux-points. Lors de l'imbrication, la délimitation externe reçoit un deux-points de plus que l'interne :

  :::::compare
  ::::option Conserver l'ancien cluster
  :::pros
  - Aucun travail de migration cette année
  :::
  :::cons
  - Aucun correctif de sécurité après mars 2028
  :::
  ::::
  ::::option Migrer vers le nouveau cluster
  :::pros
  - Supporté jusqu'en 2033
  :::
  :::cons
  - Six semaines de travail par groupe de services
  :::
  ::::
  :::::
  

• :::lead (le message de la diapositive), :::notes (notes de l'orateur) et :::source (d'où viennent les chiffres de la diapositive) doivent se trouver au niveau supérieur d'une diapositive, une fois par diapositive chacun. :::lead est réservé aux diapositives de contenu uniquement.

• date, confidential et disclaimer dans l'en-tête sont écrits une fois pour la présentation ; le modèle les place sur la couverture (et confidential dans le pied de page). Ne répétez jamais "fictif" / "confidentiel" dans une :::note sur chaque diapositive.

• Les figures sont des blocs de code délimités dont le langage est le nom du sous-système, avec un corps en YAML restreint : pas d'ancres/alias (&, *), pas de balises, pas de valeurs multi-lignes, pas de blocs |/> ; les booléens uniquement true/false ; les dates sont des chaînes YYYY-MM ou YYYY-MM-DD ; les plages 2027-01 .. 2027-06. Mettez entre guillemets toute valeur qui commence par *, &, ! ou contient ": ", par ex. text: ["**Étape la plus lente**", 5 jours en moyenne] — un **…** non guillemeté au début d'un élément de flux est interprété comme un alias YAML et rejeté.

3. Choisir un motif pour chaque contenu

Décidez du type de contenu avant d'écrire. Appliquez ces règles dans l'ordre et utilisez la première qui correspond. (Ensemble complet des règles avec exemples bons/mauvais : docs/patterns.md §4.)

Disponibles maintenant (vérifiez boxloom schema — d'autres peuvent avoir été ajoutés) :

Contenu	Utilisation	Remarques
Une pause chapitre	# Partie 2 : Comment nous migrons {type=section}	Le texte du titre est le titre du chapitre ; rien d'autre que :::notes ne peut suivre. Pas de table des matières — quand la présentation a deux sections ou plus, le modèle dessine la liste des chapitres avec la section en cours mise en évidence sur chaque diapositive de section seule
La diapositive dit exactement une phrase ; les preuves sont sur d'autres diapositives	# La migration doit être avancée de deux ans {type=statement}	Le texte du titre est la phrase (c'est le seul type de diapositive dont le titre est une phrase complète) ; rien d'autre que :::notes et :::source ne peut suivre. Si vous ajoutiez des raisons, utilisez une diapositive normale avec un titre court et la conclusion comme :::lead
1–4 nombres à mettre en évidence, sans série à comparer	::::stat → :::value 3 → 12 {unit=models} + étiquette d'une ligne à l'intérieur	5+ nombres ou une série temporelle est un graphique/tableau, pas une stat. La valeur est écrite telle quelle et doit contenir un chiffre. La valeur et l'unité ne sont jamais coupées au milieu, donc gardez-les courtes — 4 cartes sont étroites (stat-value)
Une série de nombres (3+ points) : classement, évolution, part d'un tout, distribution, relation de deux quantités	```chart	compare: item / timeSeries / component / frequency / correlation — le type de graphique est choisi pour vous (n'écrivez jamais barre/ligne/camembert). categories: [...], series: [{name, values: [...]}] (une valeur par catégorie, nombres non guillemetés, max 3 séries), unit optionnel, emphasis: [catégorie] (une série) ou emphasis: true sur une série, stacked: true quand les séries sont des parties d'un total. correlation utilise xAxis: {title, unit?}, yAxis et points: [[x, y], …] au lieu de catégories. component (part) a 1 série et ≤ 6 parties — fusionnez les petites parties dans "Autre"
Les mots de quelqu'un d'autre	:::quote Texte source + les mots à l'intérieur	La source (texte du titre) est obligatoire. Ne citez jamais votre propre conclusion
Une phrase à mettre en évidence dans une diapositive normale	:::takeaway + une phrase	Au maximum une par diapositive, généralement en dernier
Lignes × colonnes de texte simple ou de nombres	Tableau GFM : `	A
Lignes × colonnes où chaque cellule est une évaluation (supporté / conditionnel / non / risque)	```matrix	columns: [A, B], rows: [{label, cells: [{status, text?}]}], legend optionnel : {support: Bon}. Une cellule par colonne (matrix-cells). L'option recommandée : emphasis: <texte de l'en-tête de colonne> (exactement comme écrit dans columns, matrix-emphasis) — ne dites jamais "la colonne bleue" en prose. Les cellules qui sont du texte simple ou des nombres sont un tableau, pas une matrice
3–7 étapes sans dates, dans une direction (la sortie de l'une est l'entrée de la suivante)	```process	steps: [{title, detail?, status?, emphasis?}], caption optionnel. Les nombres (1. 2. …) et les flèches sont ajoutés pour vous ; les processus longs passent à une deuxième ligne. Si vous utilisez status, dites ce qu'il signifie dans legend: {conditional: Nécessite approbation} (figure-legend)
Deux options ou plus, chacune avec ses avantages et inconvénients	:::compare → :::option → :::pros / :::cons	Si 3+ critères communs s'appliquent à chaque option, une matrice convient mieux (ci-dessus)
Un parent avec des enfants (et petits-enfants) : configuration d'équipe, propriété	```orgchart	root: {title, detail?}, units: [{title, detail?, members: [{title, detail?}]}]. 3 niveaux max. Un status sur une boîte nécessite legend: {conditional: Deux personnes supplémentaires nécessaires} — la légende sous l'organigramme l'explique ; n'expliquez pas les couleurs de contour dans une :::note. Pas pour des équipes non liées côte à côte
Étapes dont le nombre diminue (visites → inscriptions → payants)	```funnel	stages: [{label, value, note?}], unit optionnel. value est un nombre ou du texte ; les largeurs de barres sont progressives, pas proportionnelles. Les taux de conversion d'étape à étape (↓ 45 %) sont dessinés pour vous à partir de valeurs numériques — ne les écrivez pas dans note ; utilisez note pour expliquer pourquoi une étape chute. status nécessite legend. Les valeurs qui augmentent sont signalées (funnel-increase) — utilisez process pour des étapes simples
Un plan daté, des périodes, des échéances, des statuts dans le temps	```gantt	Les états sont support, conditional, none, danger (rôles, pas de couleurs). Les périodes de matériel/risque de support sont un groupe risk: A .. B. Les annotations pointent vers un id de groupe/ligne via target ; le sous-système les place
2–3 groupes parallèles lus côte à côte ("cette année / l'année prochaine / pas fait")	::::columns → :::column Titre du groupe (2 ou 3)	Chaque groupe contient des paragraphes, des puces, un tableau, une image, un ```chart ou :::note. Pas de colonnes imbriquées, de comparaison, de galerie ou d'autres figures. Graphique + sa lecture côte à côte : graphique dans un groupe, les points clés sous forme de puces dans l'autre. Les largeurs ne sont pas des nombres : marquez le groupe principal {role=main} (les autres le soutiennent) ou laissez tous égaux. 4+ groupes d'une ligne → puces. Pas pour un seul argument divisé en deux
Une image qui montre le point (capture d'écran, photo, dessin)	un paragraphe contenant uniquement 	Le texte alt est obligatoire (image-alt). Le chemin est relatif au fichier de la présentation ; pas d'URL, de chemins absolus ou de .. (image-path). PNG ou JPEG uniquement (image-format). Gardé en proportion, jamais recadré. Image + texte côte à côte → ::::columns avec l'image dans un groupe
2–6 images comparées ou en séquence	un paragraphe avec 2–6 	Devient une galerie (une rangée pour 2–3, une grille pour 4–6). 7+ est une erreur : divisez la diapositive
Points parallèles	puces	2 niveaux max
Prose connectée	paragraphe	2–3 phrases
Ce que la diapositive dit : sa conclusion en une ou deux phrases	:::lead au niveau supérieur d'une diapositive de contenu, un paragraphe	Chaque diapositive de contenu en a un. Placé par le modèle juste sous le titre, en dehors du corps ; il prend de la place au corps (1 ligne ≈ 32 pt, 2 lignes ≈ 57 pt). Quand il nécessite deux lignes, le moteur le coupe après une fin de phrase (。) ou, à défaut, une virgule (、) sans ajouter de ligne — donc deux phrases courtes se lisent mieux. Pas un résumé des puces — l'affirmation qu'elles prouvent
D'où viennent les chiffres, tableaux, figures ou citations de la diapositive (source, taille d'échantillon, date)	:::source au niveau supérieur de la diapositive, un paragraphe	Chaque diapositive qui montre des nombres, un tableau, un graphique ou une citation en a un. Diapositives de contenu et de déclaration uniquement (pas de section). Placé par le modèle sous le corps, au-dessus du pied de page ; il prend de la place au corps (layout-overflow le compte). Un par diapositive : plusieurs sources vont dans un paragraphe
Date, confidentialité, avertissement à l'échelle de la présentation ("tous les chiffres sont fictifs")	en-tête date, confidential, disclaimer	Écrit une fois ; affiché sur la couverture (et confidential dans le pied de page)
Une remarque de type avertissement / note de bas de page	:::note	Une ligne courte. Pas pour les sources (:::source), pas pour l'avertissement global de la présentation (en-tête), et jamais pour la conclusion ou un chiffre clé
Un diagramme dont les positions/liens ont du sens et aucun des éléments ci-dessus ne convient	```shapes	Dernier recours, voir §3.1

Dans les quatre figures ci-dessus, vous écrivez uniquement du texte, status (support, conditional, none, danger) et emphasis: true ; la position, la taille et la couleur proviennent du modèle. Dans chart, vous écrivez uniquement ce qui est comparé et les nombres ; le graphique est un vrai graphique PowerPoint dont les valeurs restent modifiables. Mettez en évidence le seul point que le titre expose :

compare: timeSeries
unit: " inscriptions"
categories: [Avr, Mai, Juin, Juil, Août, Sep]
emphasis: [Sep]
series:
  - name: Inscriptions
    values: [120, 150, 1

…

[Le contenu a été tronqué pour la traduction]