Build-Pipeline

Diese Seite beschreibt, wie Content-Repositories das npm-Paket @f5-sales-demo/docs-theme nutzen, 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 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 Dokumentationsthema bereits über npm vorinstalliert. Zur Build-Zeit:
   • Kopiert es 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 Dokumentationsthema-Assets über npm-Paketspezifizierer auf (z. B. @f5-sales-demo/docs-theme/styles/custom.css)
5. Deployment — die erstellte statische Seite wird auf GitHub Pages bereitgestellt

Anforderungen an Content-Repositories

Ein Content-Repository benötigt lediglich:

• Ein docs/-Verzeichnis mit Markdown-(.md) oder MDX-(.mdx)-Dateien
• 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 Dokumentationsthema-Repository selbst verwendet, um die Dokumentation zu erstellen, die Sie gerade lesen.

Pfadauflösung

Alle Pfade im Dokumentationsthema verwenden npm-Paketspezifizierer, die über die exports-Map in package.json aufgelöst werden:

// CSS — aufgelöst aus node_modules
'@f5-sales-demo/docs-theme/fonts/font-face.css'
'@f5-sales-demo/docs-theme/styles/custom.css'

// Components — aufgelöst aus node_modules
'@f5-sales-demo/docs-theme/components/Footer.astro'
'@f5-sales-demo/docs-theme/components/Banner.astro'

// Assets — aufgelöst aus node_modules
'@f5-sales-demo/docs-theme/assets/github-avatar.png'

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

Hinweis

Schriftartdatei-Pfade innerhalb von font-face.css verwenden ./ (z. B. url("./neusaNextProWide-300.woff2")). Diese sind relativ zur CSS-Datei selbst, sodass sie auf andere Dateien im fonts/-Verzeichnis verweisen, unabhängig davon, wie das Paket installiert ist.

Weitergabe von Änderungen

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

1. Eine Änderung wird in @f5-sales-demo/docs-theme auf main gemergt
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 Seite des Content-Repos wird mit dem neuen Dokumentationsthema bereitgestellt

Content-Repos erhalten stets das neueste Dokumentationsthema, das im Docker-Image gebündelt ist. Dies gewährleistet visuelle Konsistenz über alle Seiten hinweg, bedeutet jedoch, dass Dokumentationsthema-Änderungen vor dem Mergen sorgfältig getestet werden sollten.