Architecture

Vue d’ensemble

Le générateur de documentation est un système conteneurisé basé sur Astro + Starlight. Les dépôts de contenu fournissent les fichiers Markdown/MDX ; le générateur fournit le framework, le thème et la logique de build. Les deux parties se rejoignent au moment du build à l’intérieur d’un conteneur Docker.

Modèle d’injection de contenu

Les dépôts de contenu conservent leur documentation dans un répertoire docs/. Au moment du build, le conteneur copie ces fichiers dans src/content/docs/, où la collection de contenu d’Astro les prend en charge.

content-repo/
  docs/           ← rédigé par les équipes de contenu
    index.mdx
    guide.mdx

docs-builder/
  src/content/docs/ ← vide au repos (.gitkeep)

Le script de point d’entrée (docker/entrypoint.sh) effectue la copie :

cp -r "$CONTENT_DIR"/* /app/src/content/docs/

Cela signifie que le dépôt du générateur lui-même est livré avec un répertoire src/content/docs/ vide. Le contenu n’apparaît qu’au moment du build.

Système de thème

Le thème Starlight est publié en tant que package npm distinct. package.json utilise un alias npm pour mapper un nom court vers le package du registre scopé :

"@f5-sales-demo/docs-theme": "^1.29.0"

Le package de thème possède astro.config.mjs. Au moment du build, le point d’entrée le copie à la racine du projet :

cp /app/node_modules/@f5-sales-demo/docs-theme/astro.config.mjs /app/astro.config.mjs

Cela permet de centraliser la configuration — les dépôts de contenu et le générateur lui-même ne maintiennent pas leur propre configuration Astro.

Organisation du répertoire source

src/
  components/
    PlaceholderForm.tsx          # Formulaire React pour l'édition des valeurs de substitution
    PlaceholderFormWrapper.astro # Wrapper Astro, charge le script DOM et le CSS global
  content/
    docs/                        # Point de montage pour le contenu injecté
  content.config.ts              # Définition de la collection de contenu Starlight
  data/
    placeholders.json            # Définitions des jetons de substitution
  lib/
    placeholder-store.ts         # Gestion d'état : charger, sauvegarder, calculer, émettre
  scripts/
    placeholder-dom.ts           # Parcours DOM côté client et rendu Mermaid

Collection de contenu

src/content.config.ts définit une collection unique docs utilisant le loader et le schéma de Starlight :

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

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
};

Tout fichier .md ou .mdx placé dans src/content/docs/ devient une page dans le site généré.

Flux de build

Le diagramme suivant illustre le pipeline de build de bout en bout lorsque le conteneur Docker s’exécute :

flowchart LR
    A[Content Repo<br/>docs/] -->|mount| B[Container<br/>/content/docs]
    B -->|entrypoint.sh<br/>cp| C[src/content/docs/]
    D[npm registry] -->|npm install| E[node_modules/<br/>@f5-sales-demo/docs-theme]
    E -->|cp astro.config| F[astro.config.mjs]
    C --> G[astro build]
    F --> G
    G --> H[dist/<br/>static HTML]
    H -->|cp| I[/output]

Traitement au moment du build vs côté client

Composant	Quand	Comment
MDX → HTML	Build	Compilateur Astro
Blocs de code Mermaid → divs conteneurs	Build	Plugin remark-mermaid.mjs (depuis docs-theme)
Jetons de substitution → spans interactifs	Client	TreeWalker dans placeholder-dom.ts
Rendu SVG Mermaid	Client	Import CDN mermaid dans placeholder-dom.ts
État du formulaire de substitution	Client	placeholder-store.ts + localStorage
Transitions de page Astro	Client	Écouteur d’événement astro:page-load