Pipeline de Build

Esta página descreve como os repositórios de conteúdo consomem o pacote npm @f5-sales-demo/docs-theme para produzir sites de documentação totalmente personalizados.

Arquitetura

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

Processo de Build Passo a Passo

1. Push no repositório de conteúdo — um push para main (ou acionamento manual) dispara o workflow de Deploy no GitHub Pages
2. Workflow reutilizável — o workflow do repositório de conteúdo chama o builder:

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

3. Execução do Docker builder — a imagem Docker f5xc-docs-builder já possui o tema pré-instalado via npm. No momento do build, ela:
   • Copia astro.config.mjs e content.config.ts de node_modules/@f5-sales-demo/docs-theme/ para a raiz do projeto Astro
   • Copia os arquivos docs/ do repositório de conteúdo para src/content/docs/
4. Build do Astro — o Astro lê a configuração que chama createF5xcDocsConfig(). A factory resolve todos os assets do tema por meio de especificadores de pacote npm (ex.: @f5-sales-demo/docs-theme/styles/custom.css)
5. Deploy — o site estático gerado é implantado no GitHub Pages

Requisitos do Repositório de Conteúdo

Um repositório de conteúdo precisa apenas de:

• Um diretório docs/ contendo arquivos Markdown (.md) ou MDX (.mdx)
• Um workflow do GitHub Actions que chame o builder

Workflow 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 é o mesmo workflow utilizado pelo próprio repositório do tema para gerar a documentação que você está lendo.

Resolução de Caminhos

Todos os caminhos no tema utilizam especificadores de pacote npm, resolvidos por meio do mapa exports no 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'

Não existe um diretório ./theme/ no workspace de build. O Docker builder instala o tema como uma dependência npm comum e o Astro resolve todos os especificadores por meio de node_modules.

Nota

Os caminhos dos arquivos de fonte dentro de font-face.css utilizam ./ (ex.: url("./neusaNextProWide-300.woff2")). Esses caminhos são relativos ao próprio arquivo CSS, portanto são resolvidos para outros arquivos dentro do diretório fonts/, independentemente de como o pacote estiver instalado.

Propagação de Alterações

As alterações no tema se propagam por meio de atualizações do pacote npm:

1. Uma alteração é mesclada em main no @f5-sales-demo/docs-theme
2. A imagem Docker do builder é reconstruída com o pacote atualizado
3. Na próxima execução do workflow de qualquer repositório de conteúdo, a imagem do builder atualizada é utilizada
4. O build do Astro incorpora as fontes, estilos, logotipo, componentes e plugins atualizados
5. O site do repositório de conteúdo é implantado com o novo tema

Os repositórios de conteúdo sempre recebem o tema mais recente incluído na imagem Docker. Isso garante consistência visual em todos os sites, mas significa que as alterações no tema devem ser testadas com cuidado antes de serem mescladas.