Build Pipeline

This page describes how content repositories consume the @f5xc-salesdemos/docs-theme npm package to produce fully branded documentation sites.

Architecture

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

Build Process Step by Step

1. Content repo push — a push to main (or manual dispatch) triggers the GitHub Pages Deploy workflow
2. Reusable workflow — the content repo’s workflow calls the builder:

   jobs:
     docs:
       uses: f5xc-salesdemos/docs-control/.github/workflows/github-pages-deploy.yml@main

3. Docker builder runs — the f5xc-docs-builder Docker image already has the theme pre-installed via npm. At build time it:
   • Copies astro.config.mjs and content.config.ts from node_modules/@f5xc-salesdemos/docs-theme/ into the Astro project root
   • Copies the content repo’s docs/ files into src/content/docs/
4. Astro build — Astro reads the config which calls createF5xcDocsConfig(). The factory resolves all theme assets through npm package specifiers (e.g., @f5xc-salesdemos/docs-theme/styles/custom.css)
5. Deploy — the built static site is deployed to GitHub Pages

Content Repo Requirements

A content repository only needs:

• A docs/ directory containing Markdown (.md) or MDX (.mdx) files
• A GitHub Actions workflow that calls the builder

Minimal 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: f5xc-salesdemos/docs-control/.github/workflows/github-pages-deploy.yml@main

This is the same workflow used by this theme repository itself to build the documentation you are reading.

Path Resolution

All paths in the theme use npm package specifiers, resolved through the exports map in package.json:

// CSS — resolved from node_modules
'@f5xc-salesdemos/docs-theme/fonts/font-face.css'
'@f5xc-salesdemos/docs-theme/styles/custom.css'

// Components — resolved from node_modules
'@f5xc-salesdemos/docs-theme/components/Footer.astro'
'@f5xc-salesdemos/docs-theme/components/Banner.astro'

// Assets — resolved from node_modules
'@f5xc-salesdemos/docs-theme/assets/github-avatar.png'

There is no ./theme/ directory in the build workspace. The Docker builder installs the theme as a regular npm dependency and Astro resolves all specifiers through node_modules.

Note

Font file paths inside font-face.css use ./ (e.g., url("./neusaNextProWide-300.woff2")). These are relative to the CSS file itself, so they resolve to other files within the fonts/ directory regardless of how the package is installed.

Change Propagation

Theme changes propagate through npm package updates:

1. A change is merged to main in @f5xc-salesdemos/docs-theme
2. The Docker builder image is rebuilt with the updated package
3. The next time any content repo’s workflow runs, it uses the updated builder image
4. The Astro build picks up the updated fonts, styles, logo, components, and plugins
5. The content repo’s site deploys with the new theme

Content repos always get the latest theme bundled in the Docker image. This ensures visual consistency across all sites but means theme changes should be tested carefully before merging.