Configuration Astro

Les dépôts de contenu ne maintiennent pas leur propre astro.config.mjs. À la place, ils importent une fabrique de configuration depuis le paquet npm @f5-sales-demo/docs-theme qui retourne une configuration Astro complète avec Starlight, huit plugins intégrés et tous les paramètres par défaut du thème.

Utilisation du thème

Le fichier astro.config.mjs d’un dépôt de contenu (fourni par le constructeur Docker) est une simple enveloppe :

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

export default createF5xcDocsConfig();

Toute personnalisation se fait via l’objet d’options ou les variables d’environnement — il n’est pas nécessaire de toucher au câblage des plugins, aux imports CSS ou aux remplacements de composants.

Options de configuration

createF5xcDocsConfig accepte un objet F5xcDocsConfigOptions. Chaque champ est optionnel ; les variables d’environnement et des valeurs par défaut sensées comblent les lacunes.

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	Valeur par défaut / Variable d’environnement	Utilité
`site`	`DOCS_SITE` ou `https://f5-sales-demo.github.io`	URL de base canonique
`base`	`DOCS_BASE` ou `/`	Chemin de base de l’URL pour les sites de projet
`title`	`DOCS_TITLE` ou `Documentation`	Titre du site dans l’en-tête et l’onglet du navigateur
`description`	`DOCS_DESCRIPTION` ou chaîne vide	Description du site pour les métadonnées et llms.txt
`githubRepository`	`GITHUB_REPOSITORY` ou chaîne vide	Active les liens d’édition et l’icône sociale GitHub
`llmsOptionalLinks`	`LLMS_OPTIONAL_LINKS` (JSON) ou `[]`	Liens supplémentaires pour le plugin llms.txt
`additionalIntegrations`	`[]`	Intégrations Astro supplémentaires à ajouter
`additionalRemarkPlugins`	`[]`	Plugins remark supplémentaires ajoutés après remark-mermaid
`megaMenuItems`	Menu intégré Produits/Solutions/Docs/Assistance	Entrées de menu méga de niveau supérieur
`head`	Balise `<script>` Mermaid CDN	Entrées `<head>` personnalisées
`logo`	`@f5-sales-demo/docs-theme/assets/github-avatar.png`	Logo de la barre latérale (src unique ou paire clair/sombre)

Plugins Starlight intégrés

La fabrique connecte automatiquement huit plugins Starlight :

Plugin	Utilité
`starlight-mega-menu`	Menu méga de navigation supérieure avec mises en page grille/liste
`starlight-videos`	Intégration de vidéos dans les pages de documentation
`starlight-image-zoom`	Zoom au clic sur les images
`@f5-sales-demo/docs-theme` (self)	Injection CSS, remplacement de composants, middleware de route
`starlight-scroll-to-top`	Bouton de retour en haut avec anneau de progression
`starlight-heading-badges`	Annotations par badge sur les titres
`starlight-page-actions`	Boutons d’action de page
`starlight-plugin-icons`	Prise en charge des icônes dans Starlight
`starlight-llms-txt`	Génère `llms.txt` et `llms-full.txt` pour la consommation par les LLM

Ceux-ci sont enregistrés dans l’ordre dans config.ts. Le plugin du thème (@f5-sales-demo/docs-theme) est lui-même un plugin Starlight qui s’exécute dans cette liste.

Hook du plugin de thème

Le plugin de thème est défini dans index.ts et enregistré parmi les plugins intégrés ci-dessus. Son hook config:setup effectue trois opérations :

Injection CSS — préfixe fonts/font-face.css et styles/custom.css dans le tableau customCss de Starlight
Remplacement de composants — remplace cinq composants Starlight :
- Banner — navigation par fil d’Ariane avec lien d’édition
- EditLink — intentionnellement vide (le lien d’édition se trouve dans Banner)
- Footer — liens vers les réseaux sociaux ajoutés sous le pied de page par défaut
- SiteTitle — logo avec lien vers l’accueil
- MarkdownContent — enveloppe activant les vidéos et le zoom sur les images
Ajout du middleware de route — enregistre route-middleware.ts qui filtre les pages d’index de la barre latérale et supprime la table des matières sur les pages d’index

// 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',
          },
        });
      },
    },
  };
}

Tous les chemins utilisent des spécificateurs de paquets npm (par ex., @f5-sales-demo/docs-theme/styles/custom.css) qui se résolvent via la carte exports dans package.json.

Autres intégrations

Au-delà de Starlight et de ses plugins, la fabrique enregistre également :

@astrojs/react — active la prise en charge des composants React dans les pages MDX
remark-mermaid — plugin remark personnalisé qui convertit les blocs de code ```mermaid en diagrammes rendus

Des intégrations supplémentaires et des plugins remark peuvent être ajoutés via les options additionalIntegrations et additionalRemarkPlugins.

Barre latérale

Aucune barre latérale personnalisée n’est définie. Starlight génère automatiquement la barre latérale à partir de la structure de fichiers dans docs/, en utilisant le frontmatter title de chaque page comme texte du lien et sidebar.order pour le tri. Le middleware de route filtre automatiquement les pages d’index de la barre latérale.