Aller au contenu
duxt

Plusieurs dépôts

Servir la documentation de plusieurs projets depuis un seul site.

Un site, plusieurs projets. Chaque dépôt source ne contient que du Markdown — pas de Nuxt, pas de package.json, pas de dépendances — ce qui est la seule organisation viable pour un projet Go, PHP ou Rust.

Étapes

  1. Nommez chaque dépôt comme une source. Un segment de dépôt apparaît dans chaque URL dès qu’il y en a plus d’un : donnez donc à chacun un slug que vous acceptez de garder, il fait partie de l’URL.
    sources: [
  { path: 'docs', slug: 'acme', origin: { repo: 'acme/site', ref: 'main' } },
  { repo: 'acme/api', path: 'docs' },
  { repo: 'acme/cli', path: 'docs' }
]
  2. Utilisez origin, pas repo, pour ce dépôt-ci. repo est ce qui fait télécharger une source par Content : y nommer le vôtre ferait cloner à la compilation le checkout dans lequel elle se trouve déjà. origin dit seulement où vivent les pages, pour le lien « Modifier cette page ».
  3. Authentifiez les dépôts privés. Content lit un jeton dans l’auth de la collection ; rien là-dedans n’est propre à duxt.
  4. Écrivez vos propres sections. La navigation fournie par la couche suppose une source unique sans préfixe. Avec un segment de dépôt dans chaque chemin, ses entrées ne se résolvent plus : nommez donc les sections vous-même, en pointant vers /acme/getting-started plutôt que /getting-started.
  5. Compilez une fois et lisez les messages. Une collection vide fait échouer la compilation, et c’est l’échec que cette configuration produit le plus souvent : un path qui n’existe pas dans l’autre dépôt ressemble exactement à un dépôt sans documentation.

Ce que vous obtenez gratuitement

La recherche interroge chaque collection sélectionnée séparément, conserve le classement propre à chacune et entrelace les mêmes positions, en commençant par la source actuelle du lecteur. Elle cherche dans la version lue ou dans la version par défaut de cette source, une par dépôt, afin qu’une page n’apparaisse pas une fois par version. _partials/ de n’importe quelle source alimente une collection partagée : une note d’installation s’écrit donc une fois et s’inclut dans les trois projets.

Liste de contrôle

  • Chaque source a un slug que vous acceptez de voir dans l’URL
  • Ce dépôt utilise origin, pas repo
  • Les sections pointent vers des chemins incluant le segment de dépôt
  • La compilation ne signale aucune collection vide
  • Une recherche depuis un dépôt trouve une page dans un autre
Cette page vous a-t-elle été utile ?