Dans l'écosystème des blogs statiques, la navigation au sein de contenus techniques denses représente un défi d'ergonomie majeur. Le thème Jekyll Chirpy répond à cette problématique via un système de table des matières (TOC - Table of Contents) dynamique et réactif. Cet article décortique les mécanismes internes de cette fonctionnalité, de la détection côté serveur à l'interaction côté client.

1. Logique de détection et activation via Liquid

Avant d'injecter du JavaScript, Chirpy utilise le moteur de template Liquid pour vérifier si l'affichage du sommaire est pertinent. Cette étape permet d'économiser des ressources en évitant de charger des scripts inutiles sur des pages courtes.

{% comment %}
  Évaluation de l'état du sommaire pour définir la variable "is_toc_enabled"
{% endcomment %}

{% assign is_toc_enabled = false %}

{% if site.toc and page.toc %}
  {% if page.content contains '<h2' or page.content contains '<h3' %}
    {% assign is_toc_enabled = true %}
  {% endif %}
{% endif %}

La logique repose sur une triple validation :

• Configuration globale : Le paramètre toc doit être activé dans le fichier _config.yml.
• Configuraton locale : Le Front Matter du fichier Markdown doit autoriser le sommaire.
• Analyse du contenu : La présence effective de balises HTML <h2> ou <h3> est requise.

2. Configuration de la bibliothèque Tocbot

Chirpy s'appuie sur Tocbot pour générer l'arborescence du sommaire. La configuration est optimisée pour garantir une synchronisation fluide entre le défilement et l'indicateur visuel.

const tocSettings = {
  tocSelector: '#toc',
  contentSelector: '.post-content',
  ignoreSelector: '[data-toc-skip]',
  headingSelector: 'h2, h3, h4',
  orderedList: false,
  scrollSmooth: true,
  headingsOffset: 32 // Correspond à l'espacement du header
};

3. Stratégies d'affichage adaptatives

Le thème distingue deux implémentations selon le périphérique utilisé, assurant une expérience utilisateur optimale sur tous les écrans.

Navigation Desktop

Sur ordinateur, le sommaire est ancré dans une colonne latérale fixe. Le script gère l'initialisation et le rafraîchissement lors des changements de taille de fenêtre.

export class DesktopNav {
  static setup() {
    tocbot.init(tocSettings);
  }

  static update() {
    tocbot.refresh(tocSettings);
  }
}

Navigation Mobile

Sur smartphone, l'espace étant restreint, Chirpy utilise l'API IntersectionObserver pour afficher ou masquer une barre de navigation flottante en fonction de la visibilité du titre principal.

export class MobileNav {
  static initializeTrigger() {
    const headerObserver = new IntersectionObserver((entries) => {
      entries.forEach((entry) => {
        const tocWidget = document.getElementById('toc-bar');
        // Masquer la barre si le titre principal est visible
        tocWidget.classList.toggle('hidden', entry.isIntersecting);
      });
    });

    const mainTitle = document.querySelector('h1');
    if (mainTitle) {
      headerObserver.observe(mainTitle);
    }
  }
}

4. Personnalisation et contrôle granulaire

Les développeurs peuvent ajuster le comportement du sommaire directement dans la configuration YAML ou via des attributs HTML spécifiques.

Exemple de configuration YAML

# Dans _config.yml
toc:
  depth_max: 3
  depth_min: 2

Exclusion de titres spécifiques

Pour empêcher un titre d'apparaître dans le sommaire sans modifier la structure globale, l'attribut data-toc-skip est utilisé :

<h2 data-toc-skip>Titre ignoré par le sommaire</h2>

5. Optimisation des performances

L'implémentation dans Chirpy suit plusieurs principes de performance :

• Enitialisation conditionnelle : Les scripts ne s'exécutent que si la varible Liquid is_toc_enabled est vraie.
• Gestion des événements : Utilisation de mécanismes de rafraîchissement intelligents pour éviter les calculs redondants lors du redimensionnement de la fenêtre.
• Accessibilité : Génération d'une structure HTML sémantique facilitant la lecture par les technologies d'assistance.