Astro-Konfiguration

Inhalts-Repositories pflegen keine eigene astro.config.mjs. Stattdessen importieren sie eine Konfigurationsfactory aus dem npm-Paket @f5-sales-demo/docs-theme, die eine vollständige Astro-Konfiguration mit Starlight, acht gebündelten Plugins und allen Standardwerten des Themes zurückgibt.

Das Dokumentationsthema verwenden

Die astro.config.mjs eines Inhalts-Repositories (bereitgestellt durch den Docker-Builder) ist ein schlanker Wrapper:

import { createF5xcDocsConfig } from '@f5-sales-demo/docs-theme/config';

export default createF5xcDocsConfig();

Alle Anpassungen erfolgen über das Optionsobjekt oder Umgebungsvariablen — Plugin-Verdrahtung, CSS-Importe oder Komponenten-Überschreibungen müssen nicht manuell bearbeitet werden.

Konfigurationsoptionen

createF5xcDocsConfig akzeptiert ein F5xcDocsConfigOptions-Objekt. Jedes Feld ist optional; Umgebungsvariablen und sinnvolle Standardwerte füllen die Lücken.

interface F5xcDocsConfigOptions {
  site?: string;
  base?: string;
  title?: string;
  description?: string;
  githubRepository?: string;
  llmsOptionalLinks?: Array<{ title: string; url: string }>;
  additionalIntegrations?: AstroIntegration[];
  additionalRemarkPlugins?: Array<unknown>;
  megaMenuItems?: MegaMenuItem[];
  head?: HeadEntry[];
  logo?: { src: string } | { light: string; dark: string };
}

Option	Standard / Umgebungsvariable	Zweck
`site`	`DOCS_SITE` oder `https://f5-sales-demo.github.io`	Kanonische Basis-URL
`base`	`DOCS_BASE` oder `/`	URL-Basispfad für Projektseiten
`title`	`DOCS_TITLE` oder `Documentation`	Seitentitel in der Kopfzeile und im Browser-Tab
`description`	`DOCS_DESCRIPTION` oder leere Zeichenkette	Seitenbeschreibung für Metadaten und llms.txt
`githubRepository`	`GITHUB_REPOSITORY` oder leere Zeichenkette	Aktiviert Bearbeitungslinks und GitHub-Social-Icon
`llmsOptionalLinks`	`LLMS_OPTIONAL_LINKS` (JSON) oder `[]`	Zusätzliche Links für das llms.txt-Plugin
`additionalIntegrations`	`[]`	Zusätzliche Astro-Integrationen zum Anhängen
`additionalRemarkPlugins`	`[]`	Zusätzliche Remark-Plugins, die nach remark-mermaid hinzugefügt werden
`megaMenuItems`	Integriertes Menü Produkte/Lösungen/Docs/Support	Oberste Mega-Menü-Einträge
`head`	Mermaid CDN `<script>`-Tag	Benutzerdefinierte `<head>`-Einträge
`logo`	`@f5-sales-demo/docs-theme/assets/github-avatar.png`	Sidebar-Logo (einzelne Quelle oder Hell/Dunkel-Paar)

Gebündelte Starlight-Plugins

Die Factory verdrahtet automatisch acht Starlight-Plugins:

Plugin	Zweck
`starlight-mega-menu`	Oberes Navigations-Mega-Menü mit Raster-/Listenlayouts
`starlight-videos`	Videos in Dokumentationsseiten einbetten
`starlight-image-zoom`	Klick-zum-Vergrößern bei Bildern
`@f5-sales-demo/docs-theme` (self)	CSS-Einbindung, Komponenten-Überschreibungen, Routen-Middleware
`starlight-scroll-to-top`	Zum-Seitenanfang-Schaltfläche mit Fortschrittsring
`starlight-heading-badges`	Badge-Annotationen an Überschriften
`starlight-page-actions`	Seitenaktionsschaltflächen
`starlight-plugin-icons`	Symbol-Unterstützung in Starlight
`starlight-llms-txt`	Generiert `llms.txt` und `llms-full.txt` für den LLM-Konsum

Diese werden der Reihe nach in config.ts registriert. Das Dokumentationsthema-Plugin (@f5-sales-demo/docs-theme) ist selbst ein Starlight-Plugin, das in dieser Liste ausgeführt wird.

Dokumentationsthema-Plugin-Hook

Das Dokumentationsthema-Plugin ist in index.ts definiert und unter den oben genannten gebündelten Plugins registriert. Sein config:setup-Hook führt drei Dinge aus:

CSS einbinden — stellt fonts/font-face.css und styles/custom.css dem customCss-Array von Starlight voran
Komponenten überschreiben — ersetzt fünf Starlight-Komponenten:
- Banner — Breadcrumb-Navigation mit Bearbeitungslink
- EditLink — absichtlich leer (Bearbeitungslink befindet sich im Banner)
- Footer — Social-Media-Links unterhalb der Standard-Fußzeile hinzugefügt
- SiteTitle — Logo mit Home-Link
- MarkdownContent — Wrapper zur Aktivierung von Videos und Bildvergrößerung
Routen-Middleware hinzufügen — registriert route-middleware.ts, das Indexseiten aus der Sidebar herausfiltert und das Inhaltsverzeichnis auf Indexseiten unterdrückt

// index.ts — Starlight plugin entry point
export default function f5xcDocsTheme(): StarlightPlugin {
  return {
    name: '@f5-sales-demo/docs-theme',
    hooks: {
      'config:setup'({ config, updateConfig, addRouteMiddleware }) {
        addRouteMiddleware({
          entrypoint: '@f5-sales-demo/docs-theme/route-middleware',
          order: 'pre',
        });
        updateConfig({
          customCss: [
            ...(config.customCss ?? []),
            '@f5-sales-demo/docs-theme/fonts/font-face.css',
            '@f5-sales-demo/docs-theme/styles/custom.css',
          ],
          components: {
            ...config.components,
            Banner: '@f5-sales-demo/docs-theme/components/Banner.astro',
            EditLink: '@f5-sales-demo/docs-theme/components/EditLink.astro',
            Footer: '@f5-sales-demo/docs-theme/components/Footer.astro',
            SiteTitle: '@f5-sales-demo/docs-theme/components/SiteTitle.astro',
            MarkdownContent: '@f5-sales-demo/docs-theme/components/MarkdownContent.astro',
          },
        });
      },
    },
  };
}

Alle Pfade verwenden npm-Paketspezifizierer (z. B. @f5-sales-demo/docs-theme/styles/custom.css), die über die exports-Map in package.json aufgelöst werden.

Weitere Integrationen

Neben Starlight und seinen Plugins registriert die Factory außerdem:

@astrojs/react — aktiviert React-Komponentenunterstützung in MDX-Seiten
remark-mermaid — benutzerdefiniertes Remark-Plugin, das ```mermaid-Codeblöcke in gerenderte Diagramme umwandelt

Zusätzliche Integrationen und Remark-Plugins können über die Optionen additionalIntegrations und additionalRemarkPlugins angehängt werden.

Es ist keine benutzerdefinierte Sidebar definiert. Starlight generiert die Sidebar automatisch aus der Dateistruktur in docs/, wobei der title-Frontmatter jeder Seite als Linktext und sidebar.order zur Sortierung verwendet wird. Die Routen-Middleware filtert Indexseiten automatisch aus der Sidebar heraus.