Pipeline de construction

Cette page décrit comment les référentiels de contenu consomment le paquet npm @f5-sales-demo/docs-theme pour produire des sites de documentation entièrement personnalisés.

Architecture

┌─────────────────┐
│  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            │
└───────────────────────────┘

Processus de construction étape par étape

1. Push du référentiel de contenu — un push vers main (ou un déclenchement manuel) active le workflow de déploiement GitHub Pages
2. Workflow réutilisable — le workflow du référentiel de contenu appelle le constructeur :

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

3. Exécution du constructeur Docker — l’image Docker f5xc-docs-builder contient déjà le thème préinstallé via npm. Au moment de la construction, elle :
   • Copie astro.config.mjs et content.config.ts depuis node_modules/@f5-sales-demo/docs-theme/ vers la racine du projet Astro
   • Copie les fichiers docs/ du référentiel de contenu dans src/content/docs/
4. Construction Astro — Astro lit la configuration qui appelle createF5xcDocsConfig(). La fabrique résout tous les actifs du thème via les spécificateurs de paquet npm (ex. : @f5-sales-demo/docs-theme/styles/custom.css)
5. Déploiement — le site statique généré est déployé sur GitHub Pages

Exigences du référentiel de contenu

Un référentiel de contenu n’a besoin que de :

• Un répertoire docs/ contenant des fichiers Markdown (.md) ou MDX (.mdx)
• Un workflow GitHub Actions qui appelle le constructeur

Workflow minimal

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

Il s’agit du même workflow utilisé par ce référentiel de thème pour générer la documentation que vous êtes en train de lire.

Résolution des chemins

Tous les chemins dans le thème utilisent des spécificateurs de paquet npm, résolus via la table exports dans 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'

Il n’existe aucun répertoire ./theme/ dans l’espace de travail de construction. Le constructeur Docker installe le thème en tant que dépendance npm ordinaire et Astro résout tous les spécificateurs via node_modules.

Note

Les chemins des fichiers de polices dans font-face.css utilisent ./ (ex. : url("./neusaNextProWide-300.woff2")). Ceux-ci sont relatifs au fichier CSS lui-même, de sorte qu’ils se résolvent vers d’autres fichiers dans le répertoire fonts/, quelle que soit la manière dont le paquet est installé.

Propagation des modifications

Les modifications du thème se propagent via les mises à jour du paquet npm :

1. Une modification est fusionnée dans main dans @f5-sales-demo/docs-theme
2. L’image Docker du constructeur est reconstruite avec le paquet mis à jour
3. La prochaine fois que le workflow d’un référentiel de contenu s’exécute, il utilise l’image du constructeur mise à jour
4. La construction Astro récupère les polices, styles, logo, composants et plugins mis à jour
5. Le site du référentiel de contenu est déployé avec le nouveau thème

Les référentiels de contenu reçoivent toujours la dernière version du thème intégrée dans l’image Docker. Cela garantit une cohérence visuelle sur tous les sites, mais implique que les modifications du thème doivent être soigneusement testées avant d’être fusionnées.