Starlight Sidebar Topics

Version : starlight-sidebar-topics@0.9.0 Starlight : @astrojs/starlight@0.42.4 Intégré le : 2026-10-13 Doc officielle : https://starlight-sidebar-topics.netlify.app

---

1. Objectif

Organiser le sidebar de la documentation en topics thématiques cliquables. Chaque topic représente un domaine technique (Astro, Cloudflare, Sanity…) et affiche sa propre arborescence de navigation quand il est sélectionné.

---

2. Installation

pnpm add starlight-sidebar-topics

---

3. Configuration dans astro.config.mjs

Le plugin s’ajoute dans le tableau plugins de starlight({}).

Important : la propriété racine sidebar: [...] de starlight doit être supprimée — le plugin la remplace entièrement.

import starlightSidebarTopics from 'starlight-sidebar-topics';

starlight({
  // PAS de sidebar: [...] ici
  plugins: [
    starlightSidebarTopics(
      [
        // Topic 1 — entrée manuelle
        {
          label: "Vue d'ensemble",
          link: '/docs/',
          icon: 'information',
          items: [
            { label: 'Accueil de la Documentation', link: '/docs/' },
          ],
        },
        // Topic 2 — autogénéré depuis un répertoire
        {
          label: 'Getting Started',
          link: '/gettingstarted/01-setup-local/',
          icon: 'rocket',
          badge: { text: '🔒', variant: 'caution' },
          items: [{ autogenerate: { directory: 'gettingStarted' } }],
        },
        // Topic 3 — avec sous-groupes
        {
          label: 'Cloudflare',
          link: '/docs/l3_backend/cloudflare/config/configobjectdata/',
          icon: 'cloudflare',
          items: [
            {
              label: 'L1 Contenu',
              items: [{ autogenerate: { directory: 'docs/L1_Contenu/cloudflare' } }],
            },
            {
              label: 'L3 Backend',
              items: [{ autogenerate: { directory: 'docs/L3_Backend/cloudflare' } }],
            },
          ],
        },
      ],
      // Options globales (2ème argument)
      {
        exclude: [
          '/docs/*.pdf',
          '/404',
          '/',
          '/index',
          '/zen-mode/**',           // routes injectées par starlight-view-modes
          '/presentation-mode/**',  // routes injectées par starlight-view-modes
        ],
      }
    ),
  ],
})

---

4. Topics configurés dans ce projet

Label	Lien d’entrée	Icône	Badge
Vue d’ensemble	/docs/	information	—
Getting Started	/gettingstarted/01-setup-local/	rocket	🔒 caution
Astro	/docs/l2_presentation/astro/...	astro	—
Cloudflare	/docs/l3_backend/cloudflare/...	cloudflare	—
Sanity	/docs/l1_contenu/sanity/...	seti:db	—
Pagefind	/docs/l2_presentation/pagefind/...	magnifier	—
Architecture & ADR	/docs/l2_presentation/adr/...	open-book	🔒 caution
Project Management	/docs/pm/...	seti:plan	🔒 caution
Standard Operating Procedure	/docs/sop/...	approve-check-circle	🔒 caution

---

5. Badges sur les topics privés

Le badge est un objet { text: string, variant: string }. Les topics réservés aux collaborateurs (non accessibles sans authentification) reçoivent un badge cadenas :

badge: { text: '🔒', variant: 'caution' }

Note : le plugin ne supporte pas d’icônes SVG dans le badge, uniquement du texte. L’emoji 🔒 est la meilleure approximation visuelle.

---

6. Conflit avec un override custom de Sidebar

starlight-sidebar-topics override le composant Sidebar de Starlight. Si le projet override également Sidebar (ex: pour ajouter un bloc auth), les deux overrides entrent en conflit.

Solution : importer overrides/Sidebar.astro du plugin

Le composant custom doit importer starlight-sidebar-topics/overrides/Sidebar.astro (qui inclut Topics + items) et non l’original Starlight.

---
// ✅ Correct : inclut topics + arborescence du topic actif
import Default from 'starlight-sidebar-topics/overrides/Sidebar.astro';

// ❌ Mauvais : bypasse les topics
// import Default from '@astrojs/starlight/components/Sidebar.astro';

// ❌ Mauvais : topics seulement, pas les items
// import Default from 'starlight-sidebar-topics/components/Sidebar.astro';
---

<Default {...Astro.props}><slot /></Default>
<!-- éléments additionnels ici -->

Voir SidebarWithAuth.astro pour l’implémentation complète.

---

7. Exclusions obligatoires

Tout plugin Starlight qui injecte de nouvelles routes (ex: starlight-view-modes) crée des pages que starlight-sidebar-topics ne reconnaît pas. Ces routes doivent être dans exclude sous peine d’erreur au build :

AstroUserError: Failed to find the topic for the `zen-mode` page.

---

8. Tests de validation

• Les topics s’affichent dans le sidebar (liste cliquable avec icônes)
• Cliquer sur un topic affiche son arborescence complète
• Les badges 🔒 apparaissent sur les 4 topics privés
• Naviguer sur une page affiche automatiquement le bon topic actif
• Les routes /zen-mode/** et /presentation-mode/** ne causent pas d’erreur