Fuentes

duxt.sources es una lista de entradas de fuente; duxt.sourceOptions dice cómo se convierten en URL. Ambas se leen en tiempo de compilación. Qué generan y por qué está en Fuentes.

#Una entrada de fuente

Dos campos son fáciles de confundir y caros de equivocar:

• repo descarga, origin solo enlaza. Nombrar tu propio repositorio en repo hace que la compilación clone el checkout en el que ya está.
• history cuesta un clon completo. Content clona un repositorio remoto con --depth 1, así que su checkout contiene un commit y cada archivo parece escrito por quien cortó la punta — datos erróneos, no datos ausentes. Activarlo completa el clon una vez. Una fuente leída del disco ya es un checkout completo y se lee de todos modos.

slug reclama un segmento. Normalmente una fuente solo recibe uno cuando la lista nombra más de un repositorio — todo o nada, para el sitio entero. Una fuente que escribe su propio slug se sirve bajo él de todas formas, y las que no escriben ninguno se quedan donde están: es lo que permite que algo viva en /demo junto a una documentación que conserva la raíz.

#Refs

Una cadena sola es una rama. Una etiqueta tiene que decirlo: git mantiene ramas y etiquetas en espacios de nombres separados, y pedir una etiqueta bajo refs/heads hace fallar la compilación con Could not find refs/heads/….

refs: [
  'main',                                     // una rama
  { branch: 'next', status: 'upcoming' },     // la misma, con un ciclo de vida
  { tag: 'v2.0.0', label: 'v2' },             // una etiqueta
  'latest'                                    // la etiqueta semver más nueva, resuelta al compilar
]

'latest' está reservado. Una rama que de verdad se llame latest necesita la forma { branch }.

#Locales

Omitido, la fuente tiene un idioma y una colección. Listado, cada entrada se convierte en una colección propia.

locales: [
  'en-GB',                                              // el predeterminado: docs/ mismo
  'de',                                                 // docs/de/
  { locale: 'fr', path: 'translations/fr' },            // en otro sitio de este repositorio
  { locale: 'es', repo: 'acme/docs-es', path: 'docs' }  // otro repositorio
]

Una cadena es una carpeta dentro del path de la fuente. La forma de objeto sobrescribe path, repo y ref solo para ese idioma — que es lo que permite que una traducción viva en un repositorio propio, con sus propios responsables y su propio calendario de publicación.

El locale por defecto es el árbol de path mismo y no ocupa carpeta. Cuál es viene de sourceOptions.defaultLocale, y tiene que coincidir con i18n.defaultLocale — la compilación falla si difieren, porque content.config.ts resuelve las colecciones sin acceso a la configuración de Nuxt.

Una ref puede llevar sus propios locales, sobrescribiendo los de la fuente igual que hace status. Esa es la forma habitual: la versión actual está traducida, las anteriores no.

refs: [
  { tag: 'v2.0.0' },                     // hereda los locales de la fuente
  { tag: 'v1.0.0', locales: ['en-GB'] }  // solo el original
]

Nombra una carpeta por idioma donde la región no aporte nada: docs/pt/ sirve tanto a pt-PT como a pt-BR, porque una página recae en su idioma base. La misma regla que siguen los archivos de locale de la propia capa.

#Estado

Lo que cada uno le cuesta a una página está en URL y versiones.

#Secciones generadas

generated lista artefactos que no son Markdown y el tipo que lee cada uno para convertirlo en páginas. Qué es el mecanismo, y las dos políticas que responde un tipo, está en Secciones generadas; los campos de debajo son los mismos sea cual sea el tipo que los lee.

path es una ruta y nunca una URL. Para una fuente que Content clona es relativa a la raíz de ese checkout, así que el artefacto viaja con la versión a la que pertenece — una regla en ambas direcciones. Una ubicación arbitraria dejaría traer un artefacto desde cualquier parte y reabriría la cuestión de la red en tiempo de compilación que sources ya cerró.

label es una cadena simple, no un texto traducido, por la misma razón que lo es la etiqueta de una versión: un texto traducido no es una URL estable.

options es opaco para todo salvo el tipo que lo lee — una granularidad significa algo para un registro de cambios y nada para una referencia de API. Una clave que el tipo no conoce hace fallar la compilación en vez de ignorarse, porque una opción mal escrita es un sitio que en silencio no obtiene lo que configuró.

#Opciones de fuente

#El manifiesto resuelto

La compilación convierte la lista anterior en duxt.resolvedSources, y eso es lo que lee el tema. useDuxtCollection() lo expone; cada entrada lleva el nombre de la colección, el prefix de URL, repo, version, isDefault, locale, isDefaultLocale, status, el repositorio y la ref de los que vinieron las páginas, y si se leyó su history.

El locale está deliberadamente ausente de prefix: i18n ya lo antepone a la ruta, así que todos los idiomas de una fuente comparten prefijo y solo se diferencian por la colección.