La consola pública sirve las guías en /docs. No requiere sesión de operador ni
acceso a GitHub. Los archivos Markdown siguen siendo la fuente del contenido;
el build los publica dentro de la salida autónoma de Nitro.
#Contenido publicado
El publicador incluye docs/es y docs/en: índices, descripción del proyecto,
política de traducción, primeros pasos, arquitectura y decisiones, proveedores,
fidelidad, funcionamiento interno, interfaces y operación. Excluye historial,
instrucciones de agentes, contratos y código de las aplicaciones. Las referencias
al material excluido conservan su texto y una explicación emergente, sin un enlace
inaccesible. Los archivos originales se conservan.
Las guías nuevas en estas secciones se descubren automáticamente. Añade un enlace
al índice Markdown del idioma para elegir su sección y orden de lectura. El
frontmatter opcional admite title, description, navigation.title y
navigation.order. Sin él, el título procede del H1 y la descripción del texto.
#Rutas y enlaces
docs/es/runtime/webhooks.md se convierte en /docs/es/runtime/webhooks. README
e index se resuelven a su ruta padre, los nombres usan minúsculas y las colisiones
detienen el build. /docs abre el índice español; cada idioma tiene URL canónica.
El resolutor compartido transforma enlaces Markdown analizados: relativos,
absolutos de documentación, parámetros de consulta, anclas y URLs conocidas del
repositorio. Los enlaces externos y las anclas conservan su significado. La misma
función de rutas se usa en la landing. Las imágenes locales bajo docs se copian
sólo si están referenciadas. HTML crudo y componentes MDX ejecutables no se admiten.
#Lectura y búsqueda
El portal usa la paleta pública, tipografía y cookie de tema existentes, con diálogos y paneles PrimeVue. Incluye navegación plegable, breadcrumbs, anclas, índice H2/H3 activo, anterior/siguiente y tablas adaptables. El código se resalta durante el build y tiene botón de copia. Los bloques Mermaid se muestran como diagramas SVG desplazables, con código desplegable y copiable. El renderizador se carga localmente sólo en páginas con diagramas y sigue el tema elegido. Sin JavaScript o si falla el renderizado, el código sigue disponible. El modo estricto de Mermaid deshabilita los enlaces de los diagramas y el HTML crudo.
Ctrl/Cmd+K abre la búsqueda local de texto completo, incluidos código y secciones. El índice se carga bajo demanda para el idioma actual; la lectura normal carga una página y metadatos de navegación. No hay servicio externo de búsqueda, analizador Markdown ni resaltador de sintaxis en el navegador.
#Validación y despliegue
npm run docs:check
npm run test:docs
npm run typecheck --workspace @payment-emulator/console
npm run build --workspace @payment-emulator/console
La publicación falla ante enlaces o anclas ausentes, imágenes inexistentes y colisiones de rutas. El diagnóstico identifica origen y destino en el log de build, nunca en la interfaz del lector. Desarrollo observa el árbol de documentos; producción necesita reconstruirse al cambiar el contenido. Docker incluye las guías actuales en el build y entrega sólo la salida Nitro en la imagen final.
Con la consola arrancada, npm run smoke:docs comprueba todas las rutas SSR,
idiomas, enlaces, anclas y el acceso anónimo. La comprobación opcional
npm run smoke:docs:browser utiliza el entorno Playwright/axe de las otras pruebas
de navegador (BROWSER_TOOLS) y verifica responsive e interacciones.
Para preparar ese entorno opcional tras una descarga limpia del repositorio:
npm install --prefix .tmp/landing-tools --no-save playwright @axe-core/playwright
npx --prefix .tmp/landing-tools playwright install chromium
npm run dev:console
En otra terminal, ejecuta npm run smoke:docs y npm run smoke:docs:browser.
La consola se busca en http://localhost:3000; configura CONSOLE_URL para usar
otra dirección. Las pruebas de navegador incluyen todos los diagramas Mermaid en
ambos temas, copia del código, cambio de idioma y desbordamiento en móvil. Las
capturas y el informe de accesibilidad se guardan en .tmp/shots/docs.