Architettura

Panoramica

Il docs builder è un sistema containerizzato basato su Astro + Starlight. I repository di contenuto forniscono file Markdown/MDX; il builder fornisce il framework, il tema e la logica di build. Le due parti si incontrano al momento della build all’interno di un container Docker.

Modello di Iniezione dei Contenuti

I repository di contenuto mantengono la propria documentazione in una directory docs/. Al momento della build, il container copia quei file in src/content/docs/, dove la content collection di Astro li raccoglie.

content-repo/
  docs/           ← creati dai team di contenuto
    index.mdx
    guide.mdx

docs-builder/
  src/content/docs/ ← vuota a riposo (.gitkeep)

Lo script di entrypoint (docker/entrypoint.sh) esegue la copia:

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

Questo significa che il repository del builder viene distribuito con una directory src/content/docs/ vuota. Il contenuto appare solo al momento della build.

Sistema dei Temi

Il tema Starlight è pubblicato come pacchetto npm separato. package.json utilizza un alias npm per mappare un nome breve al pacchetto del registro con scope:

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

Il pacchetto del tema possiede astro.config.mjs. Al momento della build, l’entrypoint lo copia nella root del progetto:

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

Questo mantiene la configurazione centralizzata — i repository di contenuto e il builder stesso non mantengono una propria configurazione Astro.

Struttura delle Directory Sorgente

src/
  components/
    PlaceholderForm.tsx          # Form React per la modifica dei valori segnaposto
    PlaceholderFormWrapper.astro # Wrapper Astro, carica script DOM e CSS globale
  content/
    docs/                        # Punto di montaggio per il contenuto iniettato
  content.config.ts              # Definizione della content collection di Starlight
  data/
    placeholders.json            # Definizioni dei token segnaposto
  lib/
    placeholder-store.ts         # Gestione dello stato: caricamento, salvataggio, calcolo, emissione
  scripts/
    placeholder-dom.ts           # TreeWalker DOM lato client e renderer Mermaid

Content Collection

src/content.config.ts definisce una singola collection docs utilizzando il loader e lo schema di 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() }),
};

Qualsiasi file .md o .mdx inserito in src/content/docs/ diventa una pagina nel sito generato.

Flusso di Build

Il seguente diagramma mostra la pipeline di build end-to-end quando il container Docker viene eseguito:

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]

Elaborazione al Momento della Build vs Lato Client

Aspetto	Quando	Come
MDX → HTML	Momento della build	Compilatore Astro
Blocchi di codice Mermaid → div container	Momento della build	Plugin remark-mermaid.mjs (da docs-theme)
Token segnaposto → span interattivi	Lato client	TreeWalker placeholder-dom.ts
Rendering SVG Mermaid	Lato client	Import CDN mermaid in placeholder-dom.ts
Stato del form segnaposto	Lato client	placeholder-store.ts + localStorage
Transizioni di pagina Astro	Lato client	Event listener astro:page-load