[🛠] Transformer les notes de bas de page du blog GitHub Pages en popovers

✨ Résumé de GPT-5.5 　

Un retour sur la réduction de la friction des notes Kramdown par défaut, qui font passer du corps du texte aux références en bas de page, en conservant la structure existante tout en transformant les liens de note dans le corps en UI de popover au format [1].

Dès que j’ai commencé à utiliser les notes de bas de page sérieusement, l’inconfort est apparu.

Quand je traite d’articles externes ou de documents dans le blog, j’ajoute maintenant des footnotes Kramdown à côté du passage concerné. Un billet comme La pénurie inédite de bulletins de vote, la colère et les dégâts causés par les extrémistes contenait beaucoup de faits, donc beaucoup de notes.

Mais à la lecture, le flux n’était pas bon.

Quand je cliquais sur un numéro de note dans le corps, aucun popup n’apparaissait. La page descendait tout en bas, vers la section Références. Comme comportement par défaut, c’est correct. Kramdown crée les notes ainsi. Mais dans un long texte, on perd facilement l’endroit où l’on lisait.

La forme des numéros de note était aussi maladroite.

Si seuls de petits chiffres comme 1 2 3 4 apparaissent, ils sont difficiles à cliquer. Sur mobile, c’est encore pire. Taper précisément un petit chiffre au milieu du texte demande plus d’attention qu’il ne devrait.

J’ai donc légèrement modifié le système de notes.

Dans le corps, elles apparaissent désormais sous la forme [1], [2], [3], et un clic ouvre un petit popover au lieu de déplacer la page vers le bas.

Je n’ai pas touché à la structure Kramdown

Je ne voulais pas changer la syntaxe Markdown ni la manière dont les footnotes sont générées.

Aujourd’hui, j’écris les notes ainsi.

Phrase du corps.[^source]

[^source]: Description de la source et lien

Cette méthode doit rester.

Côté écriture, j’utilise une syntaxe proche du Markdown standard, et au moment du build Jekyll, Kramdown génère le HTML des notes. La section Références en bas reste également. Si je remplaçais toute cette structure, il faudrait toucher les billets existants et leurs traductions.

La règle de ce travail était donc simple.

Garder le format d'écriture tel quel.
Garder les notes de bas de page générées par Kramdown.
Changer seulement l'affichage et le comportement au clic des liens de note dans le corps.

Autrement dit, conserver les données d’origine et le fallback, et améliorer uniquement l’expérience de lecture.

J’ai fait ressembler les numéros à [1]

J’ai d’abord changé le CSS.

Kramdown ajoute la classe a.footnote aux liens de note dans le corps. J’ai transformé ce lien en petit bouton inline-flex, puis ajouté les crochets avec ::before et ::after.

Résultat, dans le corps, on ne voit plus seulement un chiffre, mais ceci.

[1] [2] [3]

J’ai aussi élargi un peu la zone cliquable.

Si cela ressemble à un gros bouton, le rythme du texte se casse. Mais si cela reste un minuscule chiffre, c’est difficile à cliquer. J’ai donc ajouté une bordure et un fond très légers, tout en gardant une taille de texte plus petite que le corps.

Comme ce blog a un mode clair et un mode sombre, je n’ai pas codé les couleurs en dur. Je les ai alignées sur les variables Sass existantes.

$primary-color
$background-color
$border-color
$text-color

Ce blog charge déjà customOverride.scss après les skins claire et sombre. J’ai donc ajouté les styles de notes dans _sass/custom/customOverride.scss, sans modifier directement les fichiers originaux du thème.

Le clic crée un popover

Ensuite, le JavaScript.

Auparavant, SmoothScroll était attaché à tous les liens #hash. Un lien de note est lui aussi un lien interne vers quelque chose comme #fn:..., donc le clic faisait descendre la page en douceur.

Cette fois, j’ai d’abord intercepté uniquement les liens de note dans le corps.

La cible est celle-ci.

.page__content a.footnote[href^="#fn"]

Au clic, le script bloque le déplacement hash par défaut, trouve le contenu déjà rendu dans la liste de notes en bas, puis le clone. La note en bas contient un lien reversefootnote pour revenir au corps, mais dans le popover il n’est pas nécessaire, donc je le supprime.

Le flux est le suivant.

Clic sur une note dans le corps
-> lire le target id depuis href
-> trouver le li footnote en bas
-> cloner le contenu
-> supprimer reversefootnote
-> insérer dans le popover
-> calculer la position près du lien de note

Comme le hash ne change pas, l’URL ne se salit pas. La page ne descend pas non plus en bas.

Il y a trois manières de fermer.

Cliquer de nouveau sur la même note
Cliquer hors du popover
Esc ou le bouton de fermeture

Pour l’usage au clavier, j’ai aussi ajouté aria-haspopup="dialog" et aria-expanded. Le popover lui-même utilise role="dialog". Je ne dirais pas que c’est un composant d’accessibilité parfait, mais c’est déjà mieux qu’une div flottante sans sémantique.

Je l’ai gardé dans l’écran sur mobile

Le positionnement est important pour un popover de note.

L’afficher juste sous le lien du corps paraît naturel, mais près du bord droit ou en largeur mobile, il peut facilement sortir de l’écran.

J’ai donc forcé une marge à l’intérieur du viewport lors du calcul de position.

Au moins 12px à gauche
Au moins 12px à droite
S'il manque de place en bas, afficher au-dessus
S'il manque encore de place, clamp à l'intérieur du viewport

La largeur du popover n’est pas fixe non plus.

width: min(30rem, calc(100vw - 1.5rem));

Sur desktop, il ne devient pas trop large. Sur mobile, il ne dépasse pas la largeur de l’écran.

J’ai aussi ajouté max-height et overflow: auto pour les longues notes. L’idée est d’éviter qu’un titre d’article externe ou un lien trop long fasse recouvrir tout l’écran par le popover.

J’ai aussi régénéré le fichier minifié

Dans ce blog, assets/js/_main.js est la source, et le site publié lit assets/js/main.min.js.

Après avoir modifié le JS, j’ai donc régénéré le fichier minifié et la source map avec la tâche Rake.

bundle exec rake js

Si j’oublie cette étape, la source locale peut être corrigée alors que le site réel continue de servir l’ancien JavaScript. Pour ce type de travail, il faut vérifier ensemble le fichier source et le fichier déployé.

Ce que j’ai vérifié

J’ai vérifié ainsi.

node --check assets/js/_main.js
bundle exec rake js
bundle exec jekyll build

Ensuite, j’ai ouvert avec un serveur statique local un vrai billet contenant beaucoup de notes.

J’ai vérifié ceci.

Les liens de note apparaissent-ils sous forme [1] ?
Le hash de l'URL reste-t-il inchangé après le clic ?
La page évite-t-elle de sauter aux références du bas ?
Le popover apparaît-il ?
Le popover contient-il le contenu de la note du bas ?
En largeur mobile, le popover reste-t-il dans l'écran ?

Sur desktop, les notes du bas étaient très loin dans le document, mais après le clic sur une note, le scroll restait près du corps du texte. En largeur mobile, le popover restait aussi dans l’écran.

C’est une petite fonction, mais la lecture change beaucoup

Ce travail n’est pas une grande fonctionnalité.

Il n’y a pas de modèle de données, pas de routing, pas de nouvelle page. Il rend simplement les liens de note existants plus lisibles et ouvre un popover au clic.

Mais la sensation de lecture change nettement.

Surtout dans un billet riche en faits, les notes ne sont pas décoratives. Quand un lecteur se demande « d’où vient cette affirmation ? », il doit pouvoir vérifier immédiatement. Si cette vérification l’envoie tout en bas du billet et l’oblige ensuite à revenir au corps, les notes deviennent vite pénibles.

Désormais, pendant la lecture, on peut cliquer sur [1], vérifier et fermer.

La section Références en bas reste là. Ceux qui veulent parcourir toutes les sources à la fin peuvent toujours le faire.

C’est exactement le niveau que je voulais.

Garder la manière d’écrire en Markdown, préserver la structure Jekyll/Kramdown, et fatiguer un peu moins les doigts et les yeux du lecteur.

Même petites, ce sont ces améliorations qui doivent continuer à s’accumuler sur le blog.