Image à la une

Aperçu de ghost-toc-plugin

Modifiez les options dans le panneau de gauche. Le sommaire se redessine en direct et le code d'intégration se met à jour. Faites défiler pour voir la section courante mise en évidence.

Pour commencer

ghost-toc-plugin est un sommaire flottant minuscule (~3 Ko), sans dépendance, pour Ghost. Il a commencé comme un widget pour Ghost, mais il fonctionne aussi sur les blogs basés sur Notion, et partout où vous pouvez ajouter un script. Il lit les titres de votre article, construit la liste automatiquement, vous suit au défilement et met en évidence la section en cours de lecture. Cette page est un exemple en direct : la liste sur le côté est le vrai widget.

Installation

Ajoutez-le en une fois avec cet extrait, sans étape de build ni fichiers de thème à modifier :

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/GreedyLabs/ghost-toc-plugin@1/toc.css">
<script src="https://cdn.jsdelivr.net/gh/GreedyLabs/ghost-toc-plugin@1/toc.min.js"
        data-content=".gh-content"
        data-headings="h2,h3"
        data-title="Sommaire"></script>

Injection de code

Dans Ghost, collez-le dans Settings → Code injection → Site Footer. Sur un hébergement basé sur Notion, ajoutez-le dans le champ de code personnalisé : oopy propose une zone de code head/footer dans ses réglages, super.so a une zone Custom Code, et là vous réglez data-content sur .notion-page-content. Sur tout autre site, placez-le juste avant la balise </body>. Laissez-le sans async ni defer pour qu'il puisse lire ses propres options data-*.

Options

Tout se configure avec des attributs data-* sur la balise script : le sélecteur de contenu, les titres à inclure, le titre, la position, etc. :

data-content=".gh-content"
data-headings="h2,h3"
data-position="right"
data-min-width="1200"
data-top="100"

Personnalisation

Les couleurs et l'emplacement sont entièrement réglables. Chaque classe et variable CSS est dans l'espace de noms greedylabs-ghost-toc, donc le widget n'entre jamais en conflit avec votre thème.

Couleurs

L'élément actif suit par défaut la couleur d'accent de votre thème Ghost (--ghost-accent-color) ; utilisez data-accent ou redéfinissez les variables CSS pour la changer. Le widget fournit des valeurs claires et sombres et s'adapte automatiquement au thème du système. Pour améliorer la lisibilité en mode sombre, redéfinissez les couleurs uniquement pour le sombre, une seule valeur fixe rendrait mal en clair :

@media (prefers-color-scheme: dark) {
  .greedylabs-ghost-toc {
    --greedylabs-ghost-toc-muted: #c9d1d9;
    --greedylabs-ghost-toc-border: rgba(255,255,255,.22);
  }
}

Position

Utilisez data-position pour gauche ou droite, data-top pour le décalage en haut, data-gap pour l'espace avec le contenu et data-width pour la largeur du panneau. En dessous de data-min-width (ou s'il n'y a pas de place à côté) le sommaire se masque tout seul.

Questions fréquentes

Le widget ralentit-il mon site ?

À peine. Il pèse environ 3KB, sans dépendances ni requêtes externes. Le défilement est géré par un écouteur passif et regroupé en un seul calcul par image via requestAnimationFrame ; il ne recalcule que lorsque la hauteur du document change (images en chargement différé, giscus et widgets similaires) grâce à un ResizeObserver.

Pourquoi la table des matières ne s'affiche-t-elle pas ?

Vérifiez trois points : que votre sélecteur data-content corresponde au vrai conteneur de l'article, qu'il y ait au moins deux titres (elle ne s'affiche pas en dessous), et que la fenêtre soit plus large que data-min-width (1200px par défaut) avec de la place pour le panneau à côté du contenu. Sur les écrans étroits et mobiles, elle se masque volontairement.

Puis-je inclure des titres plus profonds comme h4 dans la table des matières ?

Oui. Listez les balises souhaitées dans data-headings, séparées par des virgules (par exemple h2,h3,h4). Vous choisissez précisément quels niveaux de titre apparaissent dans la liste.

Conclusion

ghost-toc-plugin est open source sous licence MIT ; le code et les tickets sont sur GitHub. Essayez les options dans le panneau de gauche, regardez l'aperçu se mettre à jour en direct, et copiez l'extrait quand cela vous convient. Si cela vous a aidé, un café est toujours apprécié ☕.