Configuración de Astro

Los repositorios de contenido no mantienen su propio astro.config.mjs. En su lugar, importan una fábrica de configuración del paquete npm @f5-sales-demo/docs-theme que devuelve una configuración completa de Astro con Starlight, ocho plugins integrados y todos los valores predeterminados del tema.

Consumir el tema

El archivo astro.config.mjs de un repositorio de contenido (proporcionado por el constructor Docker) es un envoltorio ligero:

import { createF5xcDocsConfig } from '@f5-sales-demo/docs-theme/config';

export default createF5xcDocsConfig();

Toda la personalización se realiza a través del objeto de opciones o de variables de entorno — no es necesario modificar el cableado de plugins, las importaciones de CSS ni las sobreescrituras de componentes.

Opciones de configuración

createF5xcDocsConfig acepta un objeto F5xcDocsConfigOptions. Todos los campos son opcionales; las variables de entorno y los valores predeterminados razonables cubren los vacíos.

interface F5xcDocsConfigOptions {
  site?: string;
  base?: string;
  title?: string;
  description?: string;
  githubRepository?: string;
  llmsOptionalLinks?: Array<{ title: string; url: string }>;
  additionalIntegrations?: AstroIntegration[];
  additionalRemarkPlugins?: Array<unknown>;
  megaMenuItems?: MegaMenuItem[];
  head?: HeadEntry[];
  logo?: { src: string } | { light: string; dark: string };
}

Opción	Valor predeterminado / Alternativa de entorno	Propósito
`site`	`DOCS_SITE` o `https://f5-sales-demo.github.io`	URL base canónica
`base`	`DOCS_BASE` o `/`	Ruta base de URL para sitios de proyectos
`title`	`DOCS_TITLE` o `Documentation`	Título del sitio en la cabecera y pestaña del navegador
`description`	`DOCS_DESCRIPTION` o cadena vacía	Descripción del sitio para metadatos y llms.txt
`githubRepository`	`GITHUB_REPOSITORY` o cadena vacía	Habilita los enlaces de edición e icono social de GitHub
`llmsOptionalLinks`	`LLMS_OPTIONAL_LINKS` (JSON) o `[]`	Enlaces adicionales para el plugin llms.txt
`additionalIntegrations`	`[]`	Integraciones Astro adicionales para agregar
`additionalRemarkPlugins`	`[]`	Plugins remark adicionales añadidos después de remark-mermaid
`megaMenuItems`	Menú integrado Products/Solutions/Docs/Support	Entradas de nivel superior del mega menú
`head`	Etiqueta `<script>` de Mermaid CDN	Entradas `<head>` personalizadas
`logo`	`@f5-sales-demo/docs-theme/assets/github-avatar.png`	Logotipo de la barra lateral (src único o par claro/oscuro)

Plugins de Starlight integrados

La fábrica conecta ocho plugins de Starlight automáticamente:

Plugin	Propósito
`starlight-mega-menu`	Mega menú de navegación superior con diseños de cuadrícula/lista
`starlight-videos`	Incrustar vídeos en páginas de documentación
`starlight-image-zoom`	Ampliar imágenes al hacer clic
`@f5-sales-demo/docs-theme` (propio)	Inyección de CSS, sobreescrituras de componentes, middleware de rutas
`starlight-scroll-to-top`	Botón de desplazamiento al inicio con anillo de progreso
`starlight-heading-badges`	Anotaciones de insignias en encabezados
`starlight-page-actions`	Botones de acción de página
`starlight-plugin-icons`	Soporte de iconos en Starlight
`starlight-llms-txt`	Genera `llms.txt` y `llms-full.txt` para el consumo por IA

Estos se registran en orden dentro de config.ts. El plugin del tema (@f5-sales-demo/docs-theme) es en sí mismo un plugin de Starlight que se ejecuta en esta lista.

Hook del plugin del tema

El plugin del tema está definido en index.ts y registrado entre los plugins integrados mencionados anteriormente. Su hook config:setup realiza tres acciones:

Inyecta CSS — antepone fonts/font-face.css y styles/custom.css al array customCss de Starlight
Sobreescribe componentes — reemplaza cinco componentes de Starlight:
- Banner — navegación de migas de pan con enlace de edición
- EditLink — intencionalmente vacío (el enlace de edición reside en Banner)
- Footer — enlaces de redes sociales añadidos debajo del pie de página predeterminado
- SiteTitle — logotipo con enlace a la página de inicio
- MarkdownContent — envoltorio que habilita vídeos y zoom de imágenes
Añade middleware de rutas — registra route-middleware.ts que filtra las páginas de índice de la barra lateral y suprime la tabla de contenidos en las páginas de índice

// index.ts — Starlight plugin entry point
export default function f5xcDocsTheme(): StarlightPlugin {
  return {
    name: '@f5-sales-demo/docs-theme',
    hooks: {
      'config:setup'({ config, updateConfig, addRouteMiddleware }) {
        addRouteMiddleware({
          entrypoint: '@f5-sales-demo/docs-theme/route-middleware',
          order: 'pre',
        });
        updateConfig({
          customCss: [
            ...(config.customCss ?? []),
            '@f5-sales-demo/docs-theme/fonts/font-face.css',
            '@f5-sales-demo/docs-theme/styles/custom.css',
          ],
          components: {
            ...config.components,
            Banner: '@f5-sales-demo/docs-theme/components/Banner.astro',
            EditLink: '@f5-sales-demo/docs-theme/components/EditLink.astro',
            Footer: '@f5-sales-demo/docs-theme/components/Footer.astro',
            SiteTitle: '@f5-sales-demo/docs-theme/components/SiteTitle.astro',
            MarkdownContent: '@f5-sales-demo/docs-theme/components/MarkdownContent.astro',
          },
        });
      },
    },
  };
}

Todas las rutas utilizan especificadores de paquetes npm (p. ej., @f5-sales-demo/docs-theme/styles/custom.css) que se resuelven a través del mapa exports en package.json.

Otras integraciones

Más allá de Starlight y sus plugins, la fábrica también registra:

@astrojs/react — habilita el soporte de componentes React en páginas MDX
remark-mermaid — plugin remark personalizado que convierte los bloques de código ```mermaid en diagramas renderizados

Se pueden añadir integraciones y plugins remark adicionales mediante las opciones additionalIntegrations y additionalRemarkPlugins.

Barra lateral

No se define ninguna barra lateral personalizada. Starlight genera automáticamente la barra lateral a partir de la estructura de archivos en docs/, utilizando el frontmatter title de cada página como texto del enlace y sidebar.order para la ordenación. El middleware de rutas filtra automáticamente las páginas de índice de la barra lateral.