Proceso de compilación

Esta página describe cómo los repositorios de contenido consumen el paquete npm @f5-sales-demo/docs-theme para producir sitios de documentación completamente personalizados con la marca correspondiente.

Arquitectura

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

Proceso de compilación paso a paso

1. Envío al repositorio de contenido — un envío a main (o despacho manual) activa el flujo de trabajo de despliegue en GitHub Pages
2. Flujo de trabajo reutilizable — el flujo de trabajo del repositorio de contenido llama al constructor:

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

3. Ejecución del constructor Docker — la imagen Docker f5xc-docs-builder ya tiene el tema preinstalado mediante npm. En el momento de la compilación:
   • Copia astro.config.mjs y content.config.ts desde node_modules/@f5-sales-demo/docs-theme/ hacia la raíz del proyecto Astro
   • Copia los archivos docs/ del repositorio de contenido en src/content/docs/
4. Compilación de Astro — Astro lee la configuración que invoca createF5xcDocsConfig(). La función de fábrica resuelve todos los recursos del tema mediante especificadores de paquetes npm (p. ej., @f5-sales-demo/docs-theme/styles/custom.css)
5. Despliegue — el sitio estático compilado se despliega en GitHub Pages

Requisitos del repositorio de contenido

Un repositorio de contenido solo necesita:

• Un directorio docs/ que contenga archivos Markdown (.md) o MDX (.mdx)
• Un flujo de trabajo de GitHub Actions que llame al constructor

Flujo de trabajo mínimo

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

Este es el mismo flujo de trabajo que utiliza este repositorio del tema para compilar la documentación que está leyendo.

Resolución de rutas

Todas las rutas del tema utilizan especificadores de paquetes npm, resueltos a través del mapa exports en 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'

No existe un directorio ./theme/ en el espacio de trabajo de compilación. El constructor Docker instala el tema como una dependencia npm regular y Astro resuelve todos los especificadores a través de node_modules.

Nota

Las rutas de archivos de fuentes dentro de font-face.css utilizan ./ (p. ej., url("./neusaNextProWide-300.woff2")). Estas son relativas al propio archivo CSS, por lo que se resuelven hacia otros archivos dentro del directorio fonts/ independientemente de cómo esté instalado el paquete.

Propagación de cambios

Los cambios en el tema se propagan a través de actualizaciones del paquete npm:

1. Un cambio se fusiona en main dentro de @f5-sales-demo/docs-theme
2. La imagen del constructor Docker se reconstruye con el paquete actualizado
3. La próxima vez que se ejecute el flujo de trabajo de cualquier repositorio de contenido, utilizará la imagen del constructor actualizada
4. La compilación de Astro incorpora las fuentes, estilos, logotipo, componentes y complementos actualizados
5. El sitio del repositorio de contenido se despliega con el nuevo tema

Los repositorios de contenido siempre obtienen el tema más reciente incluido en la imagen Docker. Esto garantiza la coherencia visual en todos los sitios, pero significa que los cambios en el tema deben probarse con cuidado antes de fusionarse.