Sources

duxt.sources est une liste d’entrées de source ; duxt.sourceOptions dit comment elles deviennent des URL. Les deux sont lues à la compilation. Ce qu’elles génèrent, et pourquoi, est dans Sources.

#Une entrée de source

Deux champs se confondent facilement et coûtent cher quand on se trompe :

• repo télécharge, origin ne fait que lier. Nommer votre propre dépôt dans repo fait cloner à la compilation le checkout dans lequel elle se trouve déjà.
• history coûte un clone complet. Content clone un dépôt distant avec --depth 1 : son checkout ne contient qu’un commit et chaque fichier paraît écrit par la personne qui a coupé la pointe — données fausses, pas données manquantes. L’activer complète le clone une fois. Une source lue sur le disque est déjà un checkout complet et est lue quoi qu’il arrive.

slug réclame un segment. Une source n’en reçoit normalement un que lorsque la liste nomme plus d’un dépôt — tout ou rien, pour le site entier. Une source qui écrit son propre slug est servie dessous de toute façon, et celles qui n’en écrivent aucun ne bougent pas : c’est ce qui permet à une chose de vivre sous /demo à côté d’une documentation qui garde la racine.

#Refs

Une chaîne nue est une branche. Un tag doit le dire : git garde les branches et les tags dans des espaces de noms séparés, et demander un tag sous refs/heads fait échouer la compilation avec Could not find refs/heads/….

refs: [
  'main',                                     // une branche
  { branch: 'next', status: 'upcoming' },     // la même, avec un cycle de vie
  { tag: 'v2.0.0', label: 'v2' },             // un tag
  'latest'                                    // le tag semver le plus récent, résolu à la compilation
]

'latest' est réservé. Une branche réellement nommée latest exige la forme { branch }.

#Locales

Omis, la source a une langue et une collection. Listées, chaque entrée devient une collection à part.

locales: [
  'en-GB',                                              // la valeur par défaut : docs/ lui-même
  'de',                                                 // docs/de/
  { locale: 'fr', path: 'translations/fr' },            // ailleurs dans ce dépôt
  { locale: 'es', repo: 'acme/docs-es', path: 'docs' }  // un autre dépôt
]

Une chaîne est un dossier à l’intérieur du path de la source. La forme objet remplace path, repo et ref pour cette langue seule — et c’est ce qui permet à une traduction de vivre dans son propre dépôt, avec ses mainteneurs et son calendrier de publication.

La locale par défaut est l’arbre de path lui-même et ne prend aucun dossier. Laquelle c’est vient de sourceOptions.defaultLocale, et elle doit concorder avec i18n.defaultLocale — la compilation échoue si elles diffèrent, car content.config.ts résout les collections sans accès à la configuration Nuxt.

Une ref peut porter ses propres locales, remplaçant ceux de la source exactement comme le fait status. C’est la forme habituelle : la version courante est traduite, les précédentes non.

refs: [
  { tag: 'v2.0.0' },                     // hérite des locales de la source
  { tag: 'v1.0.0', locales: ['en-GB'] }  // l’original seulement
]

Nommez un dossier par langue là où la région n’ajoute rien : docs/pt/ sert à la fois pt-PT et pt-BR, parce qu’une page retombe sur sa langue de base. La même règle que suivent les fichiers de locale de la couche.

#Statut

Ce que chacune coûte à une page est dans URL et versions.

#Sections générées

generated liste les artefacts qui ne sont pas du Markdown et le type qui lit chacun d’eux en pages. Ce qu’est le mécanisme, et les deux politiques auxquelles un type répond, se trouve dans Sections générées ; les champs ci-dessous sont les mêmes quel que soit le type qui les lit.

path est un chemin et jamais une URL. Pour une source que Content clone, il est relatif à la racine de ce checkout, donc l’artefact voyage avec la version à laquelle il appartient — une règle dans les deux sens. Un emplacement arbitraire permettrait d’aller chercher un artefact n’importe où et rouvrirait la question du réseau au moment du build, que sources a déjà refermée.

label est une chaîne simple et non un texte traduit, pour la même raison que le libellé d’une version en est une : un texte traduit n’est pas une URL stable.

options est opaque à tout sauf au type qui les lit — une granularité veut dire quelque chose pour un journal des versions et rien pour une référence d’API. Une clé que le type ne connaît pas fait échouer le build au lieu d’être ignorée, parce qu’une option mal orthographiée est un site qui n’obtient silencieusement pas ce qu’il a configuré.

#Options de source

#Le manifeste résolu

La compilation transforme la liste ci-dessus en duxt.resolvedSources, et c’est ce que lit le thème. useDuxtCollection() l’expose ; chaque entrée porte le nom de la collection, le prefix d’URL, repo, version, isDefault, locale, isDefaultLocale, status, le dépôt et la ref d’où viennent les pages, et si son history a été lu.

La locale est délibérément absente de prefix : i18n la place déjà devant le chemin, si bien que toutes les langues d’une source partagent un préfixe et ne diffèrent que par la collection.