Pipeline de build

Cette page décrit comment les dépôts 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            │
└───────────────────────────┘

Étapes du processus de build

1. Push sur le dépôt de contenu — un push sur main (ou un déclenchement manuel) lance le workflow de déploiement GitHub Pages
2. Workflow réutilisable — le workflow du dépôt de contenu appelle le builder :

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

3. Exécution du builder Docker — l’image Docker f5xc-docs-builder dispose déjà du thème préinstallé via npm. Au moment du build, 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 dépôt de contenu dans src/content/docs/
4. Build Astro — Astro lit la configuration qui appelle createF5xcDocsConfig(). La factory résout tous les assets du thème via les spécificateurs de paquet npm (par exemple, @f5-sales-demo/docs-theme/styles/custom.css)
5. Déploiement — le site statique généré est déployé sur GitHub Pages

Prérequis du dépôt de contenu

Un dépôt 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 builder

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 dépôt de thème pour générer la documentation que vous lisez actuellement.

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 pas de répertoire ./theme/ dans l’espace de travail de build. Le builder 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 ./ (par exemple, url("./neusaNextProWide-300.woff2")). Ces chemins sont relatifs au fichier CSS lui-même, ils se résolvent donc vers d’autres fichiers du 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 builder est reconstruite avec le paquet mis à jour
3. La prochaine fois que le workflow d’un dépôt de contenu s’exécute, il utilise l’image du builder mise à jour
4. Le build Astro intègre les polices, styles, logo, composants et plugins mis à jour
5. Le site du dépôt de contenu est déployé avec le nouveau thème

Les dépôts de contenu reçoivent toujours le dernier thème inclus dans l’image Docker. Cela garantit une cohérence visuelle sur tous les sites, mais signifie que les modifications du thème doivent être soigneusement testées avant d’être fusionnées.