Declarar la sección
El tipo de sección `changelog` — dónde vive el fichero, y las dos políticas que responde.
Un historial de versiones es una sección generada: una fuente nombra el fichero y el tipo que lo lee, y las páginas se siguen de ahí.
export default defineAppConfig({
duxt: {
sources: [
{
path: 'docs',
generated: [
{
type: 'changelog',
path: 'CHANGELOG.md',
label: 'Releases'
}
]
}
]
}
})
Los campos que toma una declaración son los mismos para cualquier tipo y están en
Fuentes. changelog nombra una opción
propia — granularity — y responde las dos
políticas de debajo.
Versionado
Por versión. Cada versión publicada de la documentación tiene su propio
registro de cambios, leído del CHANGELOG.md de esa versión y servido dentro de
ella — /releases para la versión por defecto, /v2.x/releases junto a
/v2.x/guides. Funciona exactamente como la documentación y la referencia de API
que tiene al lado.
Cada copia muestra el fichero entero que publicó esa versión, versiones anteriores incluidas, así que el registro de una versión antigua termina donde terminó esa versión. El conmutador de versiones mantiene al lector en el registro de cambios: en la página de una versión abre la misma versión en la otra, y donde esa otra nunca la tuvo abre su resumen del registro en lugar de una página que no existe.
El fichero es obligatorio en cada versión. Una versión publicada sin
CHANGELOG.md hace fallar la build, tanto para una fuente descargada como para
el repositorio que se construye — omitir la versión o mostrar allí el historial
de otra publicaría en ambos casos algo que esa versión nunca entregó.
Localización
El original, en todos los idiomas. Una colección, construida desde el idioma por defecto.
Un registro de versiones se escribe una vez, por la herramienta de releases, en el
idioma en el que el proyecto hace commits. No hay nada por idioma en él, así que un
sitio localizado sirve el original y lo dice con el
aviso de traducción que ya dibuja para una página sin
traducir. El mapa locales de la declaración solo lo leen los tipos per-locale y
aquí no hace nada.
Dónde va la entrada
navigation: 'sections' es lo predeterminado y pone la entrada en la fila de
secciones — las partes de primer nivel de la documentación.
Un registro de versiones a menudo no es una de ellas: es algo que el proyecto tiene
al lado de su documentación, no una parte de ella. navigation: 'navigation'
mueve la entrada a la primera fila, estrecha, y false no la pone en ninguna parte
y deja que el sitio la enlace.
{
type: 'changelog',
path: 'CHANGELOG.md',
label: 'Releases',
navigation: 'navigation'
}
Escribir la entrada tú mismo en navigation la mantiene donde la pusiste — la
compilación deja en paz una sección que ya encuentra en la fila, en vez de
añadirla al final. Lo cual importa, porque añadida es la última, y después de
Créditos no es donde va un registro de versiones.
El feed
duxt.feed.path nombra la sección desde la que se construye /rss.xml, y un
historial de versiones es para lo que se escribió: cada página de versión lleva el
date propio de esa versión, y una versión es algo que ocurrió — cosa que una
página de referencia editada no es.
feed: { path: '/releases', title: 'mi proyecto — versiones' }
Apagado mientras la clave no esté puesta. Solo contribuye la versión por defecto de
cada fuente, así que un sitio versionado no repite cada entrada una vez por
versión, aunque cada versión publique su propio registro de cambios. Ver Configuración y
/rss.xml.
Cuando el fichero no se puede leer
Un fichero local que no está hace fallar la compilación mientras se carga la configuración, como con cualquier tipo. Lo que el fichero no acaba de decir — un encabezado que parece una versión pero no se lee como tal — es en cambio una advertencia en el informe de compilación; ver Qué se lee y Qué comprueba la compilación.