Il y a quelques jours, j’ai publié un glossaire Kanban IT. 25 définitions, bien structurées, avec des exemples concrets. Le genre d’article qu’on écrit une fois et qu’on référence souvent.
Et c’est là que le problème a commencé.
Le constat : un glossaire inutile s’il reste dans son coin
Un glossaire, c’est bien. Mais un glossaire que personne ne trouve, c’est du contenu mort.
L’idée était simple : chaque fois que j’écris « WIPWIPle nombre d’éléments actuellement en cours dans ton système (ton board).En Kanban, le WIP est une variable de contrôle : on le limite volontairement. », « Lead TimeLead Timele temps entre “c’est demandé” et “c’est livré”.En IT : de la création du ticket (ou engagement) à sa mise en prod / clôture “Done”. » ou « ThroughputThroughputle nombre d’items terminés sur une période donnée.Ex : 18 tickets “Done” cette semaine → throughput = 18/semaine. » dans un article, je voulais que le mot devienne cliquable et renvoie vers sa définition. Avec un petit tooltip au survol pour les lecteurs pressés.
Le problème ? J’ai déjà une dizaine d’articles. Et j’en écrirai d’autres. Aller modifier chaque occurrence à la main, c’est :
- Fastidieux
- Source d’oublis
- Impossible à maintenir dans le temps
Bref, il me fallait une solution automatique.
La quête : trouver le plugin parfait
J’ai d’abord cherché dans le répertoire WordPress. Il existe des plugins de glossaire : CM Tooltip Glossary, Jesweb Glossary, etc.
Le souci ? Ils fonctionnent tous avec leur propre système de termes (un custom post type dédié). Moi, j’avais déjà mon article glossaire, bien structuré avec des H2 pour chaque terme.
Je ne voulais pas :
- Dupliquer mes définitions dans un autre système
- Maintenir deux sources de vérité
- Perdre le contrôle sur le format
Ce qu’il me fallait, c’était un plugin qui parse mon article existant et utilise directement mes H2 comme source.
Spoiler : ça n’existait pas.
La solution : un plugin maison en PHP
Alors j’ai codé le mien. Enfin, avec un peu d’aide de mon assistant IA préféré.
Le cahier des charges :
- Scanner mon article glossaire et extraire tous les termes (les H2)
- Récupérer la définition qui suit chaque H2
- Dans tous mes autres articles, transformer automatiquement chaque occurrence du terme en lien
- Afficher un tooltip au survol avec la définition tronquée
- Exclure l’article glossaire lui-même (sinon, boucle infinie de liens)
- Rafraîchir le cache automatiquement quand je modifie le glossaire
- Ouvrir les liens dans un nouvel onglet
Le résultat : un plugin de ~400 lignes de PHP, propre, maintenable, et qui fait exactement ce que je veux.
Comment ça marche (sous le capot)
1. Extraction des termes
Le plugin utilise DOMDocument pour parser le HTML de mon article glossaire. Il cherche tous les <h2>, extrait le terme principal (avant le tiret), et récupère le paragraphe « Définition » qui suit.
$h2_nodes = $xpath->query('//h2');
foreach ($h2_nodes as $h2) {
$term = $this->extract_term_from_h2($h2->textContent);
$definition = $this->find_definition_after_h2($h2);
// ...
}
2. Génération des ancres
Pour que les liens pointent directement vers la bonne section, j’utilise les ancres HTML de Gutenberg. Le plugin génère des ancres simples : wip, lead-time, throughput…
Il suffit d’ajouter ces ancres dans Gutenberg (Bloc H2 → Avancé → Ancre HTML).
3. Remplacement à la volée
Le plugin s’accroche au filtre the_content de WordPress. À chaque affichage d’article :
- Il récupère les termes depuis le cache
- Il protège les zones sensibles (liens existants, balises code, titres)
- Il remplace chaque terme par un
<span>contenant le lien + le tooltip - Il renvoie le HTML modifié
Important : l’article original en base de données n’est jamais modifié. Le remplacement se fait uniquement à l’affichage.
4. Tooltip CSS pur
Pas de JavaScript pour les tooltips. Juste du CSS avec :hover, position: absolute, et une petite flèche en pseudo-élément. Léger, rapide, compatible partout.
L’interface admin
Le plugin ajoute une page dans Réglages → Vultask Glossary.
On y trouve :
- Un sélecteur pour choisir l’article glossaire
- Un réglage pour la longueur des tooltips
- La liste de tous les termes extraits avec leurs ancres (cliquables pour copier)
- Un bouton « Rafraîchir le glossaire »
Quand j’ajoute un nouveau terme dans mon glossaire, je clique sur le bouton, et c’est propagé instantanément à tous mes articles.
Les bénéfices SEO (et UX)
Maillage interne automatique
Chaque article qui mentionne un terme Kanban pointe maintenant vers le glossaire. Google adore le maillage interne. Et mon glossaire accumule les liens entrants naturellement.
Expérience utilisateur améliorée
Un lecteur qui ne connaît pas le « WIPWIPle nombre d’éléments actuellement en cours dans ton système (ton board).En Kanban, le WIP est une variable de contrôle : on le limite volontairement. » peut survoler le mot et voir la définition sans quitter l’article. S’il veut approfondir, un clic et il arrive directement sur la section concernée.
Maintenance zéro
Je n’ai plus à penser aux liens quand j’écris. Le terme « Lead TimeLead Timele temps entre “c’est demandé” et “c’est livré”.En IT : de la création du ticket (ou engagement) à sa mise en prod / clôture “Done”. » sera automatiquement lié, que ce soit dans un article d’aujourd’hui ou dans un article écrit il y a 6 mois.
Ce que j’aurais pu faire différemment
Option 1 : Shortcodes
J’aurais pu créer un shortcode [glossaire terme="WIP"] à placer manuellement. Plus de contrôle, mais retour à la case départ : il faut y penser à chaque fois.
Option 2 : Plugin existant + adaptation
Certains plugins permettent de définir des termes manuellement. Mais je voulais une source unique de vérité : mon article.
Option 3 : JavaScript côté client
Techniquement possible, mais mauvais pour le SEO. Les bots ne voient pas toujours le contenu injecté en JS.
Le code source
Le plugin est disponible si ça t’intéresse. Il est spécifique à ma structure (H2 avec « Définition : » en dessous), mais facilement adaptable.
Les grandes lignes :
- Hook sur
the_contentpour le remplacement - Hook sur
save_postpour rafraîchir le cache quand le glossaire est modifié - Transient WordPress pour le cache (expire toutes les 24h)
- DOMDocument + XPath pour le parsing HTML
- CSS inline pour les tooltips
Conclusion : automatise ce qui peut l’être
Ce plugin m’a pris une après-midi à concevoir et tester. Il m’en fera gagner des dizaines sur le long terme.
Le maillage interne, c’est crucial pour le SEO. Mais c’est aussi le genre de tâche qu’on oublie, qu’on repousse, qu’on bâcle. En l’automatisant, je m’assure qu’il sera fait. Systématiquement. Sans y penser.
Si tu as un glossaire, une FAQ, ou n’importe quel contenu de référence que tu veux lier automatiquement dans tes articles… c’est peut-être le moment de coder ton propre petit plugin.
Ou de demander à une IA de le faire pour toi. 🦊
Tu veux voir le résultat en action ? Survole n’importe quel terme technique dans cet article. Ou va faire un tour sur mon glossaire Kanban IT.
