Comment générer automatiquement des barres latérales Starlight sans perdre le contrôle

17 août 2025 • 4 min de lecture • 700 mots

Felix Schneider

trueberryless

Avez-vous déjà voulu simplifier la génération de barres latérales dans votre projet Starlight ? Avez-vous essayé de générer automatiquement l’intégralité de la barre latérale pour découvrir qu’elle ne vous permet pas de personnaliser la structure selon vos besoins ?

Cet article démontre deux fonctionnalités de Starlight qui rendent les barres latérales entièrement générées automatiquement flexibles et réduisent la maintenance.

Cas d’utilisation

Dans des projets Starlight de taille moyenne à grande, la création et la maintenance manuelles de la configuration de la barre latérale Starlight deviennent une tâche fastidieuse et chronophage.

Par le passé, Starlight ne fournissait pas les primitives adéquates pour cela, et l’approche recommandée consistait à déplacer d’un niveau inférieur la génération automatique de la configuration de la barre latérale — afin que seuls les dossiers sans sous-dossiers imbriqués soient générés automatiquement. Cependant, avec l’introduction de Route Data et du plus récent generateId() hook de docsLoader, ces scénarios peuvent désormais être résolus beaucoup plus facilement et efficacement.

Résolution du problème d’ordre

Un problème fréquent était toujours : “Comment puis-je personnaliser l’ordre des dossiers de la barre latérale si je génère automatiquement la barre latérale ?” D’anciennes problématiques comme #1223 suggèrent une solution inspirée de Nuxt Content où chaque segment de l’intégralité du chemin peut être préfixé avec des nombres et des points pour déterminer un ordre numérique au niveau du fichier. Un exemple pour un tel projet pourrait ressembler à ceci :

• Répertoiresrc/content/docs/dossier-imbriqué

  • Répertoire1.frameworks

    • 1.vue.md
    • 2.nuxt.md
  • Répertoire2.examples

    • 1.vercel.md
    • 2.netlify.md

Si vous souhaitez utiliser cette approche dans Starlight, cela ne fonctionne pas immédiatement, mais avec une configuration simple, vous pouvez y parvenir.

Starlight 0.35.0 a introduit une fonction de rappel que vous pouvez passer à docsLoader() et qui peut manipuler l’identifiant (URL) de la page générée. En divisant l’entrée par "/" et en supprimant tout nombre + point au niveau des segments, vous disposez maintenant de la même fonctionnalité dans Starlight :

src/content.config.ts

import { defineCollection } from "astro:content";
import { docsLoader } from "@astrojs/starlight/loaders";
import { docsSchema } from "@astrojs/starlight/schema";

const leadingNumberAndDotRegEx = /^\d+\./;
const fileExtensionRegEx = /\.(md|mdx)$/;

export const collections = {
  docs: defineCollection({
    loader: docsLoader({
      // Remove file extension and
      // leading numbers + dot from each segment
      generateId: ({ entry }) =>
        entry
          .replace(fileExtensionRegEx, "")
          .split("/")
          .map((segment) => segment.replace(leadingNumberAndDotRegEx, ""))
          .join("/"),
    }),
    schema: docsSchema(),
  }),
};

L’URL pour accéder aux pages change maintenant par exemple, de /nested-folder/1.frameworks/1.vue à /nested-folder/frameworks/vue.

Cependant, les noms des dossiers dans la barre latérale incluent encore les préfixes 1.. Alors, résolvons également la manipulation de la barre latérale :

Résolution du problème de nommage des dossiers dans la barre latérale

Starlight 0.32.0 a introduit Route Data, que nous pouvons maintenant utiliser pour manipuler les noms des dossiers dans la barre latérale afin de

1. supprimer tout numéro et point en début de nom de dossier, et
2. appliquer la “Title Case” afin qu’ils ne soient pas entièrement en minuscules

src/routeData.ts

import { defineRouteMiddleware } from "@astrojs/starlight/route-data";

const leadingNumberAndDotRegEx = /^\d+\./;
const wordSplitterRegEx = /\w\S*/g;

function toTitleCase(str: string) {
  return str.replace(wordSplitterRegEx, (word) => {
    return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
  });
}

function cleanGroupLabels(entries: any[]) {
  for (const entry of entries) {
    if (entry.type === "group") {
      // Remove leading number + dot
      let label = entry.label.replace(leadingNumberAndDotRegEx, "");
      // Convert to Title Case
      entry.label = toTitleCase(label);
      // Recurse into children
      cleanGroupLabels(entry.entries);
    }
  }
}

export const onRequest = defineRouteMiddleware((context) => {
  const { sidebar } = context.locals.starlightRoute;
  cleanGroupLabels(sidebar);
});

Internationalisation (i18n)

Notez que l’internationalisation (i18n) des noms de dossiers est une fonctionnalité manquante avec une telle configuration, car il n’y a actuellement aucun endroit pour définir des traductions de noms de dossiers ; ils sont simplement convertis en “Title Case”. Implémenter une logique pour charger dynamiquement les traductions pourrait impliquer de lire le champ locale à partir des données de route et de définir les traductions dans des fichiers json. Sinon, utilisez le plugin de HiDeoo, qui prend en charge l’i18n.

N’oubliez pas d’ajouter le fichier routeData.ts à votre fichier astro.config.mjs :

astro.config.mjs

    starlight({
      title: "Autogenerate whole sidebar",
      social: [{ icon: "github", label: "GitHub", href: "https://github.com/withastro/starlight" }],
      sidebar: [
        {
          label: "Root Folder",
          autogenerate: { directory: "nested-folder" },
        },
      ],
      routeMiddleware: "./src/routeData.ts",
    }),

Bien sûr, vous pouvez ajuster le code à vos besoins (par exemple, supprimer la transformation “Title Case” si vos noms de fichiers sont déjà correctement écrits).

Utilisation du plugin de HiDeoo

Si vous souhaitez générer automatiquement toute votre barre latérale et conserver la flexibilité nécessaire pour personnaliser tout ce que vous voulez, HiDeoo a également créé un plugin dédié pour de tels cas d’utilisation : Starlight Auto Sidebar.

En particulier, ces deux fonctionnalités ont été mentionnées dans cet article :

• Controllant l’ordre des répertoires individuels
• Adaptant l’intitulé affiché des dossiers individuels

Cependant, si vous souhaitez automatiser entièrement la génération sans devoir spécifier manuellement les intitulés et l’ordre pour chaque répertoire, coder la solution vous-même (avec quelques lignes directrices de ce blog) est la solution préférée et recommandée.

Si vous souhaitez consulter le code présenté dans cet article, n’hésitez pas à visiter le StackBlitz ou le code source dans le dépôt GitHub.

Étiquettes :

• Education
• Starlight

Arrêtez d'externaliser votre âme à l'IA