Arquitetura

Visão Geral

O docs builder é um sistema containerizado baseado em Astro + Starlight. Os repositórios de conteúdo fornecem arquivos Markdown/MDX; o builder fornece o framework, o tema e a lógica de build. As duas metades se encontram no momento do build dentro de um container Docker.

Modelo de Injeção de Conteúdo

Os repositórios de conteúdo mantêm sua documentação em um diretório docs/. No momento do build, o container copia esses arquivos para src/content/docs/, onde a coleção de conteúdo do Astro os captura.

content-repo/
  docs/           ← criado pelas equipes de conteúdo
    index.mdx
    guide.mdx

docs-builder/
  src/content/docs/ ← vazio em repouso (.gitkeep)

O script de entrada (docker/entrypoint.sh) realiza a cópia:

cp -r "$CONTENT_DIR"/* /app/src/content/docs/

Isso significa que o repositório do builder é distribuído com um diretório src/content/docs/ vazio. O conteúdo só aparece no momento do build.

Sistema de Temas

O tema Starlight é publicado como um pacote npm separado. O package.json usa um alias do npm para mapear um nome curto para o pacote no registro com escopo:

"@f5-sales-demo/docs-theme": "^1.29.0"

O pacote do tema é proprietário do astro.config.mjs. No momento do build, o entrypoint o copia para a raiz do projeto:

cp /app/node_modules/@f5-sales-demo/docs-theme/astro.config.mjs /app/astro.config.mjs

Isso mantém a configuração centralizada — os repositórios de conteúdo e o próprio builder não mantêm sua própria configuração do Astro.

Estrutura do Diretório Source

src/
  components/
    PlaceholderForm.tsx          # Formulário React para editar valores de placeholder
    PlaceholderFormWrapper.astro # Wrapper Astro, carrega script DOM e CSS global
  content/
    docs/                        # Ponto de montagem para conteúdo injetado
  content.config.ts              # Definição da coleção de conteúdo Starlight
  data/
    placeholders.json            # Definições de tokens de placeholder
  lib/
    placeholder-store.ts         # Gerenciamento de estado: carregar, salvar, computar, emitir
  scripts/
    placeholder-dom.ts           # Walker DOM do lado do cliente e renderizador Mermaid

Coleção de Conteúdo

src/content.config.ts define uma única coleção docs usando o loader e schema do Starlight:

import { defineCollection } from 'astro:content';
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
};

Qualquer arquivo .md ou .mdx colocado em src/content/docs/ se torna uma página no site construído.

Fluxo de Build

O diagrama a seguir mostra o pipeline de build completo quando o container Docker é executado:

flowchart LR
    A[Content Repo<br/>docs/] -->|mount| B[Container<br/>/content/docs]
    B -->|entrypoint.sh<br/>cp| C[src/content/docs/]
    D[npm registry] -->|npm install| E[node_modules/<br/>@f5-sales-demo/docs-theme]
    E -->|cp astro.config| F[astro.config.mjs]
    C --> G[astro build]
    F --> G
    G --> H[dist/<br/>static HTML]
    H -->|cp| I[/output]

Processamento em Tempo de Build vs Tempo de Cliente

Preocupação	Quando	Como
MDX → HTML	Tempo de build	Compilador Astro
Blocos de código Mermaid → divs container	Tempo de build	Plugin remark-mermaid.mjs (do docs-theme)
Tokens de placeholder → spans interativos	Tempo de cliente	TreeWalker em placeholder-dom.ts
Renderização SVG do Mermaid	Tempo de cliente	Importação CDN do mermaid em placeholder-dom.ts
Estado do formulário de placeholder	Tempo de cliente	placeholder-store.ts + localStorage
Transições de página do Astro	Tempo de cliente	Listener do evento astro:page-load