Sources

Une source est un dossier de Markdown : dans ce dépôt ou dans un autre, sur le checkout courant ou sur des refs nommées. La liste sources est le seul endroit où on les déclare, et tout le reste en est généré.

sources: [
  { path: 'docs', slug: 'acme' },
  { repo: 'acme/api', path: 'docs', refs: ['main', 'v2.0.0', 'v1.4.0'] }
]

Deux dépôts et trois refs : cinq collections, les préfixes d’URL qui les servent, un sélecteur de versions, les règles de redirection et les entrées du sitemap. Rien de tout cela n’est écrit à la main. Chaque champ figure dans la référence des sources.

#Comment cela fonctionne

Content v3 fait déjà la moitié difficile. La source d’une collection accepte une URL de dépôt, une branche ou un tag et des identifiants, et Content la télécharge puis la met en cache par hachage — multi-dépôts, dépôts privés et lecture depuis un tag existent déjà là. duxt n’en réimplémente rien.

Ce que duxt ajoute se produit au chargement de la configuration. content.config.ts est du code exécuté et non un fichier de données : il peut donc lire l’app.config.ts du site et calculer ses collections à partir de cette liste — une collection par dépôt × ref, chacune avec un cwd absolu, un nom dérivé du slug et le schéma de page dont le thème a besoin. La même liste est résolue une seconde fois par la compilation, en manifeste : quelle collection sert quel préfixe d’URL, quelle ref est celle par défaut, d’où vient chaque page. C’est ce manifeste que le thème lit, et il est réécrit dans la configuration de l’application sous resolvedSources.

#Pourquoi c’est construit ainsi

Déclarer les collections à la main ne passe pas à l’échelle dans la seule direction où la documentation grandit vraiment : trois versions sur quatorze dépôts font quarante-deux déclarations, et chaque publication en modifie quatorze. Le raccourci garde la liste aussi longue que le nombre de projets.

Le coût, c’est qu’une liste de sources exprime moins qu’une collection écrite à la main. C’est un compromis délibéré : qui a besoin de ce que le raccourci ne sait pas dire écrit son propre content.config.ts et reprend tout, puisque Content fusionne le fichier de chaque couche, la dernière l’emportant.

#Ce qui en découle

Parce qu’une source nomme un dépôt, une ref et un dossier, plusieurs fonctionnalités n’ont besoin d’aucune configuration propre : « Modifier cette page », la date de dernière modification et la liste des contributeurs en découlent toutes. Lire l’historique d’une source distante coûte un clone complet : cela attend donc history: true — un clone superficiel attribuerait chaque fichier à l’auteur de la pointe, ce qui est une donnée fausse plutôt qu’une donnée manquante.