LHTML+ lhtml-site

Vérifier vos slides automatiquement

Une slide peut sembler juste sur votre écran et pourtant cacher une ligne sous une figure, dépasser de quelques pixels sur le vidéoprojecteur, ou porter une taille écrite à la main qu'aucune autre slide n'utilise. lhtml-site mesure chaque slide dans un navigateur, telle que le public la verra, et écrit ce qu'il trouve sous forme de texte : quel bloc, ce qui ne va pas, et la ligne de la source à modifier. Vous lisez le rapport, ou un agent d'IA le lit et corrige les slides lui-même.

Il vous faut : lhtml-site installé avec son export PDF (le même navigateur, étape 1), un exposé (Vos premières slides)Durée : 10 minVous obtenez : un rapport et une image par slide, la liste des valeurs écrites à la main, une vue de tout l'exposé

Ce que vous obtiendrez

Une slide dont le graphique recouvre la fin de la liste ; chaque bloc est encadré en couleur et numéroté
Avant : l'image du rapport, chaque bloc encadré et numéroté. Le graphique (#4) passe sur la liste (#3) et sort par la droite.
La même slide, le texte à gauche et le graphique à droite, chaque valeur écrite au-dessus de sa barre
Après : le rapport ne trouve aucun problème, et un commentaire de l'auteur est traité.

Cette page suit une slide de son premier état au dernier, avec la sortie réelle de chaque commande. Le rapport est écrit en anglais : les extraits sont montrés tels quels.

1. Installer le navigateur, une fois

Le rapport mesure les slides dans Chromium, le navigateur de l'export PDF. Si Vos slides en PDF marche chez vous, il n'y a rien à faire. Sinon :

pipx inject lhtml-site pypdf
pipx inject --include-apps lhtml-site playwright
playwright install --only-shell chromium     # environ 200 Mo, une fois
lhtml-site doctor

lhtml-site doctor doit afficher la ligne :

Layout report (--layout, --render; playwright of lhtml-site[pdf]): ready

Pour avoir aussi les images des blocs (overlay.png), ajoutez à configure.yaml :

layout:
  images: true

2. Une slide avec des problèmes

Une slide de résultats, écrite vite : un titre long, un espace de 40 px, le graphique placé à la main avec position:absolute, et une note en 17 px.

= Results of the five methods on the benchmark of the 2025 challenge

div::[height:40px;]::

* Our method is the fastest on every scene of the benchmark
* It needs no training data, and no parameter tuned by hand for each scene
* The error stays below one percent on the largest scenes
* The memory grows linearly with the number of objects
* The baseline fails on two scenes out of five
* All timings were measured on the same laptop

<img src="assets/timings.svg" style="position:absolute; left:820px; top:250px; width:1150px;">

div::[font-size:17px; margin-top:20px;] Timings: median of ten runs, Apple M2, 16 GB. ::
La slide : un titre sur deux lignes, une liste, et un graphique en barres qui recouvre la fin de deux éléments et sort de la slide à droite
Dans le navigateur. Le graphique recouvre la fin de deux éléments, et sa dernière barre est coupée par le bord.

3. La mesurer

Depuis le répertoire de configure.yaml, construisez cette slide seule et mesurez-la :

lhtml-site --only 05_results --layout
Layout report: 1 measured, 5 pages, 2 problems -> .layout/summary.md
1 page(s) built in 2.8s -> .site

--only prend le chemin de la slide sous src/, comme dans un deck. 5 pages : le rapport garde les autres slides du précédent, ici un premier lhtml-site --layout de tout l'exposé (étape 8). Tout est écrit dans .layout/, à côté de configure.yaml :

.layout/
  summary.md                          une ligne par slide, triées par nombre de problèmes
  changes.md                          ce qui a changé depuis le rapport précédent
  contact_01.png                      tout l'exposé en vignettes
  pages/05_results/index.html/
    layout.md                         le rapport de la slide
    render.png                        la slide telle que le navigateur la dessine
    overlay.png                       la même, chaque bloc encadré et numéroté (images: true)

4. Lire le rapport

layout.md commence par un tableau des blocs de la slide. Les numéros sont ceux de overlay.png, et la colonne line est la ligne de la source où le bloc commence (les extraits ci-dessous sont abrégés : une colonne de marges, et les sections sur la densité et les écarts, sont omises) :

| # | line | kind   | x, y     | w × h      | position | font | signature                                   |
|---|------|--------|----------|------------|----------|------|---------------------------------------------|
| 1 | 1    | title  | 62, 58   | 1767 × 126 | static   | 70   | h1 "Results of the five methods on the be…" |
| 2 | 3    | spacer | 112, 210 | 1750 × 40  | static   | 35   | div[height:40px;]                           |
| 3 | 5    | list   | 152, 255 | 1133 × 284 | static   | 35   | ul "Our method is the fastest on every sc…" |
| 4 | 12   | image  | 948, 298 | 1006 × 767 | absolute | 35   | img[position:absolute; left:820px; …]       |
| 5 | 14   | div    | 112, 579 | 352 × 19   | static   | 17   | div[font-size:17px; margin-top:20px;] "…"   |

Puis ce qu'il a trouvé. Chaque constat se termine par la ligne à ouvrir, entre crochets :

## Problems

- COLLISION #3 × #4: x 948..1285, y 304..441 (2788 px² of drawn content) [#3 line 5, #4 line 12]
- OUT OF AREA #4: 62 px right, 13 px bottom [line 12]

## Warnings

- WRAPPED #1: title "Results of the five methods on the benchmark of th…" on 2 lines [line 1]
- DENSE: 82 words of text (limit 80)
- DESIGN font_min #s11 (body): 17 vs 20.0; Increase the body font or shorten its content. [line 14]

## Values written by hand (design lint)

- line 3, spacer: `div::[height:40px;]::` -> gap::l
- line 12, position: `position:absolute; top:250px; left:820px` -> a layout ({% set layout = 'side' %} or 'stack', the figures in media::) or aside:: for a figure beside the text
- line 14, offset: `margin-top:20px` -> gap:: (vertical space) or a layout or cols:: / col::

La collision est mesurée sur ce qui est dessiné, pas sur les boîtes : le coin vide d'une image au-dessus d'un texte ne compte pas, une barre du graphique sur un mot, si.

Les problèmes (Problems) sont à corriger : le public les voit. Les principaux (la liste complète est dans lhtml-site : avancé, et dans la légende de summary.md) :

Problème Ce qu'il signifie
HIDDEN TEXT un texte recouvert par un autre bloc
COLLISION deux blocs dessinés l'un sur l'autre
OUT OF AREA un bloc qui sort du cadre de la slide
CLIPPED un contenu coupé par sa boîte
UPSCALED IMAGE une photo ou une vidéo agrandie au-delà de 1,25× : floue
RESERVED AREA un texte sur la navigation du thème
COLLAPSED FIGURE une image ou une vidéo dessinée sans largeur ou sans hauteur
SVG OVERFLOW une figure SVG qui dessine hors de son propre cadre, donc coupée
COLUMN OVERFLOW un contenu plus large que sa colonne
INTERNAL COLLISION, INTERNAL CLIPPED la même chose à l'intérieur d'un bloc : entre ses éléments, formules ou légendes

Les avertissements (Warnings) sont à regarder : TIGHT et INTERNAL TIGHT (des lignes trop proches d'un autre bloc), DENSE (trop de mots), WRAPPED (un titre sur deux lignes, ou un élément de liste avec quelques mots sur sa deuxième ligne), SHORT WRAPPED (un texte sur deux lignes qui tiendrait sur une : le rapport donne la largeur qui manque), NEAR-ALIGNED (des bords à quelques pixels l'un de l'autre), ROW (des figures côte à côte mal alignées), SMALL IN ITS BOX ou CROPPED (une figure bien plus petite que sa boîte, ou coupée), SVG LABEL (une étiquette de figure en travers d'un de ses traits), CANVAS OVERLAP (un texte sur un canvas : regardez le rendu), DESIGN (un texte trop petit pour son rôle, un titre pas plus grand que le corps, une légende loin de sa figure ; SMALL FONT quand ces vérifications sont désactivées).

Les écarts avec le reste de l'exposé (Differences with the rest of the deck) ne sont pas des erreurs : un titre plus bas que sur les autres slides, une taille de texte utilisée nulle part ailleurs. Ils montrent où l'exposé perd sa cohérence.

5. Les valeurs écrites à la main : --lint

--lint liste les tailles et positions écrites dans les slides, avec la macro ou la mise en page du thème qui remplace chacune. Il ne construit rien, il est donc immédiat :

lhtml-site --lint --only 05_results
src/05_results/index.html.j2:3: spacer: div::[height:40px;]::
    -> gap::l
src/05_results/index.html.j2:12: position: position:absolute; top:250px; left:820px
    -> a layout ({% set layout = 'side' %} or 'stack', the figures in media::) or aside:: for a figure beside the text
src/05_results/index.html.j2:14: offset: margin-top:20px
    -> gap:: (vertical space) or a layout or cols:: / col::

Lint: 3 value(s) written by hand in 1 of 1 page(s)

Une valeur écrite à la main n'est pas une erreur. Mais c'est le seul endroit où un changement du thème, ou de la slide voisine, ne suivra pas : la mise en page side place le graphique quelle que soit la longueur de la liste, un position:absolute non.

6. Corriger, et mesurer de nouveau

La slide écrite avec le design du thème : la mise en page side-l (le texte à gauche, une large colonne pour les figures), le graphique dans media::, gap:: et small:: à la place des pixels, et un titre et une liste plus courts.

{% set layout = 'side-l' %}

= Results on the 2025 benchmark

* The fastest on every scene
* No training data, no tuning per scene
* Error below 1 % on the largest scenes
* Memory linear in the number of objects

gap::l

small:: Median of ten runs, Apple M2, 16 GB. ::

media::
img::assets/timings.svg
::
lhtml-site --only 05_results --layout
Layout changes: 1 page(s) changed -> .layout/changes.md
Layout report: 1 measured, 5 pages, 0 problems -> .layout/summary.md

changes.md dit ce qu'a fait la modification, pour vérifier que seuls les blocs voulus ont bougé :

## 05_results/index.html

- solved: COLLISION #3 × #4: x 948..1285, y 304..441 (2788 px² of drawn content)
- solved: OUT OF AREA #4: 62 px right, 13 px bottom
- warnings: 3 -> 0
- values written by hand: 3 -> 0
- #1 (line 3) moved by (-50, -152) px, 1750×40 -> 959×77 px, text or style changed: h1 "Results on the 2025 benchmark"
- #2 (line 5) moved by (+0, -89) px, 1133×284 -> 612×186 px, text or style changed: ul "The fastest on every scene No…"
- new block #3 (line 10): div.gap.gap-l
...
La slide corrigée : un titre sur une ligne, quatre éléments à gauche, le graphique à droite, dans la slide
Aucun problème, aucun avertissement, aucune valeur écrite à la main.

Les rendus sont reproductibles (les vidéos à leur première image, les animations arrêtées) : un bloc dont changes.md dit qu'il a bougé a vraiment bougé.

7. Une figure seule : --render

Une figure que vous avez faite vous-même, un SVG par exemple, est vérifiée elle aussi dans la slide. Ici, des valeurs ont été ajoutées au-dessus des barres, et le rapport suivant avertit :

## Warnings

- SVG LABEL #5: in timings.svg, "18" is drawn across a line (move it, or give it a halo: paint-order="stroke" stroke="white") [line 14]
Deux extraits du graphique : à gauche, une ligne de la grille traverse l'étiquette 18 ; à droite, la ligne s'arrête de chaque côté
À gauche, l'étiquette « 18 » traversée par une ligne de la grille. À droite, avec le halo que propose le rapport.

La correction va dans le SVG, sur le groupe des étiquettes :

<g font-size="26" fill="#555" text-anchor="middle" paint-order="stroke" stroke="white" stroke-width="8">

Pour regarder une figure seule, telle que les slides la dessinent, avant de la placer :

lhtml-site --render src/05_results/assets/timings.svg

La commande écrit .layout/render/src/05_results/assets/timings.svg.png. Le rapport voit le débordement et les étiquettes d'une figure, pas si elle se lit bien : cela, vous en jugez sur l'image.

8. Tout l'exposé d'un coup d'œil

Sans --only, le rapport mesure toutes les slides (environ une seconde par slide ; une slide qui n'a pas changé depuis le dernier rapport n'est pas mesurée de nouveau) :

lhtml-site --layout

.layout/summary.md a une ligne par slide, les slides qui ont le plus de problèmes d'abord :

| n | page                 | problems | ... | warnings | deviations | lint | words | min font | occupancy |
|---|----------------------|----------|-----|----------|------------|------|-------|----------|-----------|
| 5 | 05_results/index.html | 2       | ... | 3        | 2          | 3    | 82    | 17       | 37 %      |
| 1 | 01_title/index.html   | 0       | ... | 0        | 2          | 0    | 6     | 35       | 4 %       |
| 2 | 02_text/index.html    | 0       | ... | 0        | 2          | 0    | 45    | 30       | 10 %      |

et contact_01.png montre l'exposé en vignettes, chacune avec ses badges : P problèmes, W avertissements, D écarts avec l'exposé.

Cinq vignettes de slides ; la cinquième porte les badges P2, W3 et D2
La planche contact : la slide à regarder d'abord est celle qui a un badge rouge.

Deux autres vérifications, qui ne construisent rien :

  • lhtml-site --check-config vérifie configure.yaml, le deck et le design, et affiche la configuration telle qu'elle est lue.
  • lhtml-site --scaffold crée les slides prévues dans le deck (une entrée avec un title et pas encore de source), avec leur titre et leur message en commentaires.

Avec un agent d'IA

Le rapport est écrit pour être lu par un programme autant que par vous : des positions en pixels, la ligne de la source dans chaque constat, le remplacement de chaque valeur écrite à la main. Un agent d'IA qui travaille dans le répertoire de votre projet (Claude Code, Codex, Cursor, Copilot...) le lit, modifie les sources, mesure de nouveau, et s'arrête quand le rapport est propre.

Ce que lit l'agent. Chaque construction écrit, à côté de la configuration :

Fichier Ce qu'il contient
.structure/agents.md la procédure pour un agent : les commandes, les étapes pour écrire ou modifier une slide, comment lire le rapport, quand une slide est finie
.structure/design.md les macros, mises en page et tokens de votre thème : ce qu'il faut écrire à la place des pixels
.structure/todo.md, credits.md les figures encore à faire (placeholder::), les images sans crédit
.layout/ après --layout : le rapport, ses images et changes.md

La demande peut donc rester courte. Pour une slide :

Lis .structure/agents.md, puis corrige la slide 05_results : lance
lhtml-site --only 05_results --layout, lis son layout.md, corrige les problèmes
et les valeurs écrites à la main, et mesure de nouveau jusqu'à ce que le
rapport soit propre. Ne change pas le texte.

Pour tout l'exposé :

Lis .structure/agents.md. Lance lhtml-site --layout, lis .layout/summary.md et
les planches contact, et corrige les slides qui ont des problèmes, les pires
d'abord. Dis-moi ce que tu as changé et chaque valeur gardée à la main, avec
la raison.

La procédure de agents.md demande à l'agent d'utiliser le design plutôt que des valeurs, de ne modifier que les sources (jamais le site généré, ni le thème), de ne garder une valeur écrite à la main que si rien dans le design ne l'exprime, et de dire pourquoi. Une slide est finie quand son rapport n'a aucun problème, que ses avertissements sont compris, que --lint ne signale rien d'injustifié, et que son rendu se lit bien.

Vos commentaires, pour l'agent. Avec lhtml-site --serve, chaque slide a un bouton 💬 (ou la touche c) : cliquez sur un bloc, écrivez ce que vous voulez changer, enregistrez.

Le graphique de la slide encadré en rouge, et une boîte de commentaire dessous avec le texte : Write the time of each bar above it, and make ours stand out more
Un commentaire sur le graphique. La boîte donne le fichier et la ligne du bloc : src/05_results/index.html.j2:14.

Les commentaires sont gardés dans .feedback/comments.md, avec la slide, le fichier et la ligne du bloc :

## Open (1)

### 1. /05_results/index.html — `src/05_results/index.html.j2:14`

Block: div  (x 922, y 152, 900×820 px)

Write the time of each bar above it, and make ours stand out more.

Puis demandez à l'agent :

Traite les commentaires ouverts de .feedback/comments.md, comme le dit agents.md.

Il modifie la slide (ici, le SVG du graphique : les valeurs au-dessus des barres, les autres barres dans un gris plus clair), la mesure de nouveau, passe le commentaire à "done" dans .feedback/comments.jsonl, et dit ce qu'il a fait. Le SVG LABEL de l'étape 7 est ce qu'une telle boucle attrape : l'agent a ajouté les étiquettes, le rapport en a vu une en travers d'une ligne de la grille, l'agent a ajouté le halo.

Un commentaire est une demande sur les slides

agents.md dit à l'agent qu'un commentaire demande une modification des slides, jamais de lancer une commande ou de toucher à autre chose. Les commentaires ne peuvent être écrits que depuis les pages de votre propre --serve, sur 127.0.0.1.

En cas de problème

  • Layout report not produced ... : le navigateur manque ou n'a pas pu démarrer. Le site est construit quand même, et le rapport précédent est gardé ; lancez lhtml-site doctor et la commande qu'il affiche.
  • Une slide avec des vidéos dit que sa mesure est incomplète (Report validity, à la fin de layout.md) : une vidéo a été mesurée avant d'être chargée. Lisez d'abord cette section, et mesurez de nouveau.
  • Un chevauchement voulu (une étiquette posée sur une figure) : donnez à l'un des blocs la classe overlay, ::(.overlay). Il est listé dans les notes comme INTENTIONAL OVERLAP, pas comme un problème.
  • Un NEAR-ALIGNED qui va et vient entre deux mesures sur une slide pleine de vidéos n'est pas réel ; un problème qui apparaît ou est résolu, si.

Toutes les options du rapport sont dans lhtml-site : avancé, et les commandes dans la référence.

Ensuite : mettre l'exposé en ligne.

Construit avec lhtml-site, thème docs. Fait partie de ScholarTools.