Saltar al contenido principal

El sitio de documentación, medido

zudocs lo había tratado como una plantilla que funcionaba: compilaba y no tenía enlaces rotos. Antes de la 0.2.0 lo revisé como lo que es, un producto que va a ejecutar la documentación de otros proyectos. Estas son las notas de esa revisión, del 16 y 17 de noviembre de 2026. Las fuentes que contrasté: la documentación de Docusaurus 3.10.2, llmstxt.org y el código instalado de Docusaurus y del buscador.

Lo grave​

Tres cosas que no eran de aspecto.

Qué encontréPor qué importabaQué hice
build borraba la carpeta de salida sin comprobar cuál era. Con outDir: "." vaciaba el proyectoEs un comando que ejecuto sobre proyectos ajenosLa plantilla se niega a usar una carpeta de salida que no sea segura: la raíz, la carpeta personal, una que contenga la documentación, la configuración, los estáticos o la plantilla, o una con contenido que no parezca un sitio compilado
--config sin valor compilaba en silencio el sitio de zuix en vez del pedido, y una opción mal escrita (--strcit) se ignoraba: la verificación pasaba sin modo estrictoUn error de tecleo daba un resultado verdeCada comando declara sus opciones; lo demás es un error de uso, con código de salida 2
Las casillas de las listas de tareas no tenían nombre accesibleaxe lo marca como críticoReciben una etiqueta

La configuración​

La configuración solo se validaba en verify, no al compilar, y el validador no aplicaba todo el esquema. brand entraba sin filtrar en una ruta de archivo, y el identificador de un área, en rutas del sitio.

Ahora se valida al cargar, en todos los comandos, y el esquema tiene patrones para los campos que acaban en una ruta o en una URL. Un campo desconocido es un error con sugerencia. Lo decidí así porque la configuración la va a editar un agente, y un agente que se inventa un campo necesita que alguien se lo diga.

Contenido que no escribo yo​

Un <script> escrito en un .md llegaba tal cual al HTML y se ejecutaba en el navegador: el modo en que Docusaurus lee los .md no sanea HTML. Para mi documentación no es un problema; para una plantilla que compila la documentación de un tercero, sí.

Dos medidas, que se complementan:

  • markdown.untrusted: verify rechaza los .mdx, que son código, y el HTML activo en los .md.
  • zudocs headers: una política de seguridad de contenido que autoriza por su hash solo los scripts en línea que aparecen en todas las páginas, que son los de la plantilla. Uno que aparece solo en algunas viene del contenido y queda bloqueado. Comprobé con un documento hostil que el script no se ejecuta.

La segunda tiene un límite: GitHub Pages no aplica cabeceras propias. Allí solo vale la primera.

Fuentes de terceros​

Cada visita pedía la hoja y cinco archivos a Google Fonts. Eso es tres problemas a la vez: la dirección IP del visitante llega a un tercero, la petición bloquea el pintado y obliga a abrir la política de contenido a otro origen.

Las del sitio de zuix están autoalojadas: diez woff2, 173 kB, con licencia OFL, y fonts admite una hoja local. Una URL remota sigue funcionando, con aviso.

Para bajarlas escribí un comando, zudocs fonts, que descargaba la hoja y sus archivos y escribía una hoja local. Lo quité antes de publicarlo: un comando que trae archivos de internet y los escribe en el repositorio es lo que las políticas de dependencias del proyecto evitan, y el análisis estático lo señalaba con razón (una URL de la configuración llega a una petición, y lo descargado llega al disco). Las fuentes se autoalojan a mano o con un paquete @fontsource/* (Zudocs).

De paso encontré que las fuentes de menos de 10 kB se incrustaban en el CSS como data:, 73 kB más de CSS bloqueante. Bajé ese límite.

Peso​

El paquete común del sitio llevaba los 346 iconos en sus dos variantes: 1.189 kB (340 kB con gzip) en todas las páginas, para dibujar unos cuarenta. Ahora el paquete común registra solo los iconos que el sitio puede dibujar, y las páginas de iconos y de componentes cargan el set completo. Quedó en 624 kB (196 kB con gzip).

Medidas con Lighthouse 13.6, en móvil simulado, sobre el sitio compilado y servido en estático con gzip:

PáginaAntes: rendimiento · LCP · TBT · JSDespués: rendimiento · LCP · TBT · JS
Portada91 · 1,6 s · 340 ms · 397 kB99 · 0,9 s · 150 ms · 260 kB
Un documento de uso93 · 1,6 s · 310 ms · 378 kB95 · 0,9 s · 250 ms · 237 kB
Un documento de investigación95 · 1,6 s · 230 ms · 373 kB99 · 0,9 s · 140 ms · 233 kB
Componentes78 · 1,8 s · 880 ms · 459 kB76 · 1,1 s · 1.210 ms · 421 kB
Iconos88 · 2,2 s · 360 ms · 371 kB92 · 1,5 s · 340 ms · 346 kB
Tokens90 · 1,6 s · 380 ms · 339 kB99 · 0,9 s · 130 ms · 200 kB

El desplazamiento acumulado del diseño es 0 en todas, antes y después. Una primera tanda de medidas "antes" la hice mientras corría otra suite de pruebas y dio entre 55 y 84 de rendimiento: la descarté por ruido.

La página de componentes no mejora: hidrata más de setenta demostraciones a la vez y su tiempo de bloqueo en móvil simulado ronda 1,2 s. Arreglarlo exige cargar el catálogo por grupos, que es cambiar la página. No es una regresión y lo dejé para después.

Accesibilidad y medios​

Qué encontréQué hice
Texto con el color de acento por debajo de 4,5:1 en migas, paginación, enlaces e índice (de 3,76 a 3,96:1)El token nuevo --z-accent-text
El tema claro del código con comentarios, cadenas y etiquetas entre 2,47 y 4,14:1Un tema claro propio con esos colores oscurecidos
Sin estilos de impresión: página oscura y con el cromo visibleEstilos de impresión
Sin prefers-reduced-motion ni forced-colors fuera de los componentesAñadidos a la hoja del sitio
La etiqueta del buscador fija en inglés y la página de resultados sin región principalEnvolví los dos componentes del buscador
El logo con un texto alternativo igual al título contiguo, que se leía dos vecesTexto alternativo vacío por defecto

La puntuación de accesibilidad de Lighthouse en los documentos pasó de 97 a 100. Vale lo que vale una auditoría automática.

Lo que ven los buscadores y los modelos​

  • El sitio se compilaba con un dominio inexistente: canónicas, sitemap y Open Graph apuntaban a él. Ahora url y baseUrl son campos de la configuración, hay imagen para compartir y se genera robots.txt.
  • Sin trailingSlash fijado, en GitHub Pages cada página interior redirigía y la canónica no coincidía. El valor por defecto es false.
  • llms.txt tenía rutas relativas, resúmenes cortados a mitad de palabra y la portada de cada área al final. Lo reescribí conforme a llmstxt.org: URL absolutas, la primera frase completa de cada documento y la portada primero. Añadí llms-full.txt y una copia .md de cada documento.

Verificación​

verify no veía anclas rotas, front matter inválido, imágenes inexistentes, rutas duplicadas, documentos fuera de área, títulos repetidos ni marcadores de plantilla sin rellenar. Ahora sí. Lo probé con los documentos de zuix y con los de mi piloto local, sin falsos positivos.

Y escribí una prueba del sitio compilado (pnpm test:site): sirve el sitio bajo su baseUrl con la política de contenido activa y recorre todas las páginas del sitemap en dos temas y tres anchos, en tres motores.

Lo que dejé sin arreglar​

QuéPor qué
El buscador no encuentra «documentacion» sin tildeEl índice (lunr) no pliega diacríticos y el plugin no ofrece la opción
La página de componentes hidrata todo a la vezExige rehacer la página
Los textos de la portada y de los catálogos solo están en españolUn sitio con locale: "en" los muestra en español; falta traducirlos
La política de contenido no se aplica en GitHub PagesEl alojamiento no admite cabeceras propias
robots.txt bajo /zuix/Los buscadores solo lo leen en la raíz del dominio
El icono de la pestaña solo existe en SVGSin .ico ni icono para iOS

Lo que no he comprobado​

  • El despliegue real en GitHub Pages. Compilé y recorrí el sitio servido bajo /zuix/ en local.
  • El rendimiento del desenfoque en hardware real: Lighthouse corre en un Chrome sin GPU y en móvil simulado.
  • prefers-reduced-transparency fuera de Chromium.
  • Safari real y lectores de pantalla.