Generador del sitio de documentación — Starlight

Fecha: 2026-09-03 · Estado: Decidida · Decide: Product Engineering Lead Alcance: Capa B de 000-dev-ops-model · Resuelve: decisión abierta D3 del T0

Decisión

El sitio de documentación —interno y externo— se construye con Starlight (sobre Astro).

Contexto

La plataforma sirve tres consumidores desde una sola fuente de markdown en Git: el equipo interno tras autenticación, los portales externos de cara al cliente, y el corpus de los agentes de IA. El contenido se agrega de 17 repos y content/ se regenera completo en cada build. Las cuatro alternativas evaluadas fueron Docusaurus, Starlight, Material for MkDocs y Mintlify.

Razonamiento

Los dos factores que cerraron la decisión fueron deal-breakers, no el total ponderado:

1. Búsqueda detrás del login. La búsqueda de Docusaurus depende de Algolia rastreando el sitio desde afuera, y eso no funciona en un sitio que exige sesión válida. Starlight trae Pagefind, que indexa en el build y corre del lado del cliente: la búsqueda funciona tras la autenticación sin exponer el contenido a un tercero.
2. Velocidad de build a escala. Starlight sobre Astro es estático y rápido; Docusaurus sobre React reconstruye más lento a medida que crecen los repos — y aquí el árbol completo se regenera en cada corrida del sync.

El versionado nativo por app, única ventaja clara de Docusaurus, no aplica: todas las apps de Prism corren sobre una sola versión.

Cuadro comparativo

Criterios ponderados según los requisitos de este proyecto. Importancia y puntaje van de 1 a 5; el total es Σ(importancia × puntaje) sobre un máximo de 145. Los puntajes son juicio informado, no medición: el cuadro sirvió como guía de conversación, no como veredicto.

Criterio	Imp.	Docusaurus	Starlight	Material for MkDocs	Mintlify (gestionado)
Búsqueda detrás de login (sitio interno)	5	3	5	4	4
Velocidad de build a escala	4	3	5	4	5
Bajo mantenimiento / simplicidad (equipo chico)	4	3	4	5	5
Encaje docs-as-code multi-repo + corpus de agentes	5	5	5	5	2
Versioning nativo por app	2	5	2	4	3
Ecosistema / plugins / extensibilidad	3	5	3	3	2
i18n ES/EN sin fricción	3	4	5	3	3
Chat de IA / help desk externo listo	3	2	2	2	5
Total ponderado (máx. 145)		107	120	113	106

Cómo leerlo:

• Starlight (120) puntea arriba con estos pesos, empujado por búsqueda tras autenticación, velocidad de build e i18n nativo — justo lo que pesa en el sitio interno.
• Material for MkDocs (113) es el más simple de mantener y perfecto como fuente de markdown para agentes; pierde en extensibilidad y en lo visual para el sitio externo.
• Docusaurus (107) es el más maduro y extensible, y el único con versionado nativo de primera clase; si el versionado por app o el ecosistema de plugins subiera de importancia, tomaría la delantera.
• Mintlify (106) gana en “cero mantenimiento” y chat de IA listo, pero cae fuerte en el encaje con el diseño multi-repo y el corpus de agentes propio, y es de pago.

Sensibilidad: subir versionado a 4–5 o ecosistema a 5 → gana Docusaurus. Poner bajo mantenimiento por encima de todo → gana Mintlify o MkDocs.

Consecuencias

• La búsqueda del sitio interno es Pagefind, del lado del cliente. No hay dependencia de un servicio externo de indexación, ni contenido interno saliendo a un tercero.
• Los sitios son estáticos: la autenticación no vive en el generador sino en el reverse proxy delante, con Core Identity (Tech Spec §8).
• El cableado del contenido no es la ruta directa de Docusaurus: Starlight lee su colección de docs desde content/, fuera del proyecto del sitio (Tech Spec §7).
• La decisión es reversible a bajo costo y así debe seguir siendo: el contenido es markdown plano con front-matter en Git, y el generador es una capa intercambiable sobre él. Es el principio de independencia de herramienta aplicado (02 §7 A8).

Alternativa si se revierte

Docusaurus sobre el mismo content/, aceptando resolver la búsqueda tras login por otra vía (índice propio o un servicio auto-hospedado). Nada del contenido ni del sync cambia.