Secciones generadas

Una fuente publica el Markdown que guarda un repositorio. Una sección generada publica algo que no es Markdown en absoluto: una fuente nombra un artefacto y el tipo que lo lee, y las páginas se siguen de ahí.

{
  path: 'docs',
  generated: [
    { type: 'changelog', path: 'CHANGELOG.md', label: 'Releases' },
    { type: 'openapi', path: 'openapi.yaml', label: 'API' }
  ]
}

La capa trae dos tipos — changelog y openapi — y el registro está abierto, así que un sitio puede añadir los suyos o sustituir uno de estos. Los campos que toma una declaración son los mismos para cualquier tipo y están en Fuentes.

#Las páginas son una colección corriente

Este es el punto entero, y merece decirse con claridad: lo que produce un tipo son ficheros Markdown, escritos en una colección que Content construye como cualquier otra. Así que la búsqueda las encuentra, llms.txt las lista, el sitemap las lleva, el conmutador de versiones se mueve entre ellas, y el control de copia entrega la página a un modelo.

Nada aquí es una segunda vía de renderizado. Un tipo que tuviera que enseñarse a la búsqueda, o al feed, o al sitemap, sería un sitio paralelo dentro del sitio — y cada una de esas costuras es un lugar por el que las dos mitades se separan.

#Qué le pertenece a un tipo, y qué no

Un tipo responde tres preguntas y nada más: cómo partir su artefacto en páginas, y las dos políticas de debajo. No decide dónde va su entrada en la barra, cómo se llama la sección, ni qué artefacto lee — eso pertenece a la declaración, porque pertenece al sitio.

#Versionado

Los dos son opuestos, y ambos son correctos. Una descripción de API pertenece a la versión que describe: a un lector en v1 que pregunta qué significa un campo no se le puede mostrar la respuesta de v2. Un registro de cambios es lo contrario — no es un documento por versión que menciona otras versiones, es la lista de las versiones, y construir una copia por versión publicaría el mismo fichero bajo tres URL, a cada una le faltarían las versiones que vinieron después.

Que el mismo mecanismo produzca ambos es por lo que el versionado es una política del tipo y no una regla de la capa.

#Localización

Un tipo per-locale lee el mapa locales de la declaración — un artefacto por idioma, porque una descripción OpenAPI traducida es un artefacto de verdad y no el mismo fichero reetiquetado. Un idioma que el mapa no nombra no construye nada, y es deliberado: la cadena de reserva existente le sirve entonces el idioma por defecto y el aviso de traducción lo dice. Declarar un artefacto para cada idioma y servir en silencio el mismo fichero bajo cada uno dejaría ese aviso mudo y al lector sin enterarse.

Un tipo original se salta el mapa por completo. Un registro de versiones se escribe una vez, por la herramienta de releases, en el idioma en el que el proyecto hace commits — así que un sitio localizado sirve el original y lo dice con el aviso que ya dibuja.

#Dónde fallan

Un artefacto local que falta, no se puede leer, o recibe una opción que su tipo no conoce hace fallar la compilación mientras se carga la configuración: la configuración propia del sitio es un error que la compilación no debe cargar, y una sección que se quedó vacía en silencio es una sección cuya ausencia nadie nota.

Lo que queda es o un artefacto remoto, que puede haber quedado legítimamente obsoleto entre una versión y la siguiente, o una página que renderizó con algo de menos. Eso son advertencias en el informe de compilación — ver Qué comprueba la compilación.