Pipeline di build

Questa pagina descrive come i repository di contenuto consumano il pacchetto npm @f5-sales-demo/docs-theme per produrre siti di documentazione completamente brandizzati.

Architettura

┌─────────────────┐
│  Content Repo   │
│  (docs/ folder) │
└────────┬────────┘
         │
         ▼
┌───────────────────────────┐
│   f5xc-docs-builder       │
│   (Docker image)          │
│                           │
│  npm install              │
│  @f5-sales-demo/docs-theme ─────┐  │
│                        ▼  │
│  node_modules/            │
│    @f5-sales-demo/docs-theme/       │
│      ├── config.ts        │
│      ├── index.ts         │
│      ├── fonts/           │
│      ├── styles/          │
│      ├── assets/          │
│      └── components/      │
│                           │
│  Astro Build              │
└─────────────┬─────────────┘
              ▼
┌───────────────────────────┐
│   Astro Build Output      │
│   (static HTML/CSS)       │
└─────────────┬─────────────┘
              ▼
┌───────────────────────────┐
│   GitHub Pages            │
└───────────────────────────┘

Processo di build passo dopo passo

1. Push sul repository di contenuto — un push su main (o un avvio manuale) attiva il workflow di deploy su GitHub Pages
2. Workflow riutilizzabile — il workflow del repository di contenuto richiama il builder:

   jobs:
     docs:
       uses: f5-sales-demo/docs-control/.github/workflows/github-pages-deploy.yml@main

3. Esecuzione del builder Docker — l’immagine Docker f5xc-docs-builder ha già il tema pre-installato tramite npm. Al momento della build:
   • Copia astro.config.mjs e content.config.ts da node_modules/@f5-sales-demo/docs-theme/ nella root del progetto Astro
   • Copia i file docs/ del repository di contenuto in src/content/docs/
4. Build Astro — Astro legge la configurazione che richiama createF5xcDocsConfig(). La factory risolve tutti gli asset del tema tramite specificatori di pacchetti npm (es. @f5-sales-demo/docs-theme/styles/custom.css)
5. Deploy — il sito statico compilato viene distribuito su GitHub Pages

Requisiti del repository di contenuto

Un repository di contenuto necessita soltanto di:

• Una directory docs/ contenente file Markdown (.md) o MDX (.mdx)
• Un workflow GitHub Actions che richiama il builder

Workflow minimale

name: GitHub Pages Deploy
on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  docs:
    uses: f5-sales-demo/docs-control/.github/workflows/github-pages-deploy.yml@main

Questo è lo stesso workflow utilizzato da questo stesso repository del tema per compilare la documentazione che stai leggendo.

Risoluzione dei percorsi

Tutti i percorsi nel tema utilizzano specificatori di pacchetti npm, risolti tramite la mappa exports in package.json:

// CSS — resolved from node_modules
'@f5-sales-demo/docs-theme/fonts/font-face.css'
'@f5-sales-demo/docs-theme/styles/custom.css'

// Components — resolved from node_modules
'@f5-sales-demo/docs-theme/components/Footer.astro'
'@f5-sales-demo/docs-theme/components/Banner.astro'

// Assets — resolved from node_modules
'@f5-sales-demo/docs-theme/assets/github-avatar.png'

Non esiste alcuna directory ./theme/ nell’area di lavoro della build. Il builder Docker installa il tema come una normale dipendenza npm e Astro risolve tutti gli specificatori tramite node_modules.

Nota

I percorsi dei file font all’interno di font-face.css utilizzano ./ (es. url("./neusaNextProWide-300.woff2")). Questi sono relativi al file CSS stesso, quindi si risolvono negli altri file all’interno della directory fonts/ indipendentemente da come il pacchetto viene installato.

Propagazione delle modifiche

Le modifiche al tema si propagano tramite aggiornamenti del pacchetto npm:

1. Una modifica viene integrata in main nel repository @f5-sales-demo/docs-theme
2. L’immagine Docker del builder viene ricostruita con il pacchetto aggiornato
3. La prossima volta che il workflow di qualsiasi repository di contenuto viene eseguito, utilizza l’immagine del builder aggiornata
4. La build Astro recepisce i font, gli stili, il logo, i componenti e i plugin aggiornati
5. Il sito del repository di contenuto viene distribuito con il nuovo tema

I repository di contenuto ricevono sempre il tema più recente incluso nell’immagine Docker. Questo garantisce la coerenza visiva tra tutti i siti, ma significa che le modifiche al tema devono essere testate accuratamente prima dell’integrazione.