Build-Pipeline

Diese Seite beschreibt, wie Content-Repositories das npm-Paket @f5-sales-demo/docs-theme konsumieren, um vollständig gebrandete Dokumentationsseiten zu erstellen.

Architektur

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

Build-Prozess Schritt für Schritt

1. Push ins Content-Repo — ein Push auf main (oder ein manueller Dispatch) löst den GitHub Pages Deploy-Workflow aus
2. Wiederverwendbarer Workflow — der Workflow des Content-Repos ruft den Builder auf:

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

3. Docker-Builder wird ausgeführt — das Docker-Image f5xc-docs-builder hat das Theme bereits über npm vorinstalliert. Zur Build-Zeit wird Folgendes ausgeführt:
   • Kopiert astro.config.mjs und content.config.ts aus node_modules/@f5-sales-demo/docs-theme/ in das Astro-Projektstammverzeichnis
   • Kopiert die docs/-Dateien des Content-Repos nach src/content/docs/
4. Astro-Build — Astro liest die Konfiguration, die createF5xcDocsConfig() aufruft. Die Factory löst alle Theme-Assets über npm-Paket-Spezifikatoren auf (z. B. @f5-sales-demo/docs-theme/styles/custom.css)
5. Deployment — die erstellte statische Website wird auf GitHub Pages bereitgestellt

Anforderungen an das Content-Repo

Ein Content-Repository benötigt lediglich:

• Ein docs/-Verzeichnis mit Markdown-Dateien (.md) oder MDX-Dateien (.mdx)
• Einen GitHub Actions-Workflow, der den Builder aufruft

Minimaler Workflow

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

Dies ist derselbe Workflow, den dieses Theme-Repository selbst verwendet, um die Dokumentation zu erstellen, die Sie gerade lesen.

Pfadauflösung

Alle Pfade im Theme verwenden npm-Paket-Spezifikatoren, die über die exports-Zuordnung in package.json aufgelöst werden:

// 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'

Im Build-Workspace gibt es kein ./theme/-Verzeichnis. Der Docker-Builder installiert das Theme als reguläre npm-Abhängigkeit, und Astro löst alle Spezifikatoren über node_modules auf.

Hinweis

Schriftartdateipfade innerhalb von font-face.css verwenden ./ (z. B. url("./neusaNextProWide-300.woff2")). Diese sind relativ zur CSS-Datei selbst und werden daher unabhängig von der Installationsweise des Pakets auf andere Dateien im fonts/-Verzeichnis aufgelöst.

Weitergabe von Änderungen

Theme-Änderungen werden über npm-Paketaktualisierungen weitergegeben:

1. Eine Änderung wird in @f5-sales-demo/docs-theme in main zusammengeführt
2. Das Docker-Builder-Image wird mit dem aktualisierten Paket neu erstellt
3. Beim nächsten Ausführen des Workflows eines Content-Repos wird das aktualisierte Builder-Image verwendet
4. Der Astro-Build übernimmt die aktualisierten Schriftarten, Stile, Logos, Komponenten und Plugins
5. Die Website des Content-Repos wird mit dem neuen Theme bereitgestellt

Content-Repos erhalten stets das neueste Theme, das im Docker-Image gebündelt ist. Dies gewährleistet eine einheitliche visuelle Darstellung auf allen Websites, bedeutet jedoch, dass Theme-Änderungen vor dem Zusammenführen sorgfältig getestet werden sollten.