Sidebar-Konfiguration

Die Sidebar in Pathfinder wird über lokalisierte TypeScript-Dateien konfiguriert, die Aufbau und Reihenfolge deiner Dokumentations-Tabs und ihrer Abschnitte festlegen.

Konfigurationsdateien

Die Sidebar-Navigation wird in src/docs/config/[language]/sidebarNavData.json.ts konfiguriert. Jede Sprachdatei exportiert ein Standardobjekt, das die Dokumentations-Tabs und ihre Abschnitte enthält.

export default {
  // Tabs definieren, die oben in der Sidebar erscheinen
  tabs: [
    {
      id: "main",
      title: "Dokumentation",
      description: "Hauptdokumentation",
      icon: "tabler/file-text", // Optionales Icon aus astro-icon
      // Abschnitte definieren, die in diesem Tab erscheinen
      sections: [
        {
          id: "getting-started",
          title: "Erste Schritte",
        },
        {
          id: "components",
          title: "Komponenten",
        },
        {
          id: "reference",
          title: "Referenz",
        },
      ],
    },
    {
      id: "api",
      title: "API",
      description: "API-Referenz",
      icon: "tabler/api-app",
      sections: [
        {
          id: "endpoints",
          title: "Endpunkte",
        },
        {
          id: "authentication",
          title: "Authentifizierung",
        },
      ],
    },
  ],
};

Struktur im Überblick

Die Sidebar-Konfiguration besteht aus:

1. Dokumentations-Tabs – Sie erscheinen oben in der Sidebar und ermöglichen es Nutzer:innen, zwischen verschiedenen Dokumentationsbereichen zu wechseln (wie „Dokumentation” und „API”).

2. Sidebar-Abschnitte – Das sind die Abschnitte innerhalb jedes Dokumentations-Tabs. Sie stehen für Ordner mit zusammengehörigen Dokumentationsseiten.

Eigenschaften von Dokumentations-Tabs

Jeder Tab im tabs-Array hat die folgenden Eigenschaften:

• id (erforderlich): Die eindeutige Kennung dieses Dokumentations-Tabs.
• title (erforderlich): Der angezeigte Titel des Tabs in der Sidebar-Navigation.
• description (optional): Eine kurze Beschreibung des Tab-Inhalts.
• icon (optional): Ein Icon aus dem astro-icon-Set, das neben dem Tab-Titel angezeigt wird.
• sections (erforderlich): Ein Array der Sidebar-Abschnitte, die zu diesem Tab gehören.

Eigenschaften von Sidebar-Abschnitten

Jeder Abschnitt im sections-Array eines Tabs hat die folgenden Eigenschaften:

• id (erforderlich): Muss dem Ordnernamen unter src/docs/data/docs/[language]/ entsprechen. Ist deine id beispielsweise „getting-started”, müssen deine Dokumentationsdateien unter src/docs/data/docs/[language]/getting-started/ liegen.
• title (erforderlich): Der angezeigte Titel des Abschnitts in der Sidebar-Navigation. Er darf Leerzeichen und Sonderzeichen enthalten.

Reihenfolge und Organisation

• Die Reihenfolge der Tabs im tabs-Array bestimmt ihre Anzeigereihenfolge im Tab-Selector der Sidebar.
• Die Reihenfolge der Abschnitte im sections-Array eines Tabs bestimmt ihre Anzeigereihenfolge innerhalb des Tabs.
• Wenn ein Tab ausgewählt wird, zeigt die Sidebar die Abschnitte dieses Tabs in der konfigurierten Reihenfolge an.

Neue Tabs und Abschnitte hinzufügen

Einen neuen Dokumentations-Tab hinzufügen:

1. Füge dem tabs-Array eine neue Tab-Konfiguration mit einer eindeutigen id hinzu
2. Definiere die Abschnitte, die in diesem Tab erscheinen sollen

Einen neuen Abschnitt zu einem bestehenden Tab hinzufügen:

1. Lege einen neuen Ordner unter src/docs/data/docs/[language]/ mit der ID deines Abschnitts an
2. Füge dem sections-Array des passenden Tabs eine neue Abschnittskonfiguration hinzu
3. Füge deine Dokumentationsdateien (.md oder .mdx) in den neuen Abschnittsordner ein

export default {
  tabs: [
    {
      id: "main",
      title: "Dokumentation",
      // ... weitere Eigenschaften ...
      sections: [
        // ... bestehende Abschnitte ...
        {
          id: "advanced-topics",
          title: "Fortgeschrittene Themen",
        },
      ],
    },
  ],
};

Lokalisierung

Die Sidebar-Navigation lässt sich vollständig lokalisieren. Lege für jede Sprache eine eigene Konfigurationsdatei an (automatisiert über den Befehl docs:config-i18n):

• src/docs/config/en/sidebarNavData.json.ts für Englisch
• src/docs/config/fr/sidebarNavData.json.ts für Französisch
• usw.

Jede Sprache kann eigene übersetzte Titel und Beschreibungen haben und bei Bedarf sogar eine abweichende Reihenfolge von Tabs und Abschnitten nutzen.