URL et versions
Comment apparaissent les segments de dépôt et de version, et ce qu’on dit à un lecteur dans une ancienne version.
Chaque page est servie à
/[repo]/[version]/[...chemin]
les deux préfixes étant facultatifs — et la décision de faire apparaître chacun est prise à la compilation, à partir de la liste des sources, jamais par requête.
- Un segment de dépôt apparaît dès qu’il y a plus d’un dépôt, ou quand
showRepole force ou — pour cette source seule — lorsque la source déclare son propreslug. - Un segment de version apparaît dès qu’une source publie plus d’une ref, ou
quand
showVersionle force.
Un dossier unique non versionné sert donc /guides/deploying, et rien dans
l’URL ne trahit l’existence de dépôts ou de versions.
Pourquoi les préfixes sont décidés à la compilation
Si les deux préfixes étaient facultatifs par requête, le premier segment serait
ambigu : /guides/… pourrait être un dossier, un dépôt ou une version, et seule
la consultation des trois le dirait. Comme la forme d’une URL est figée avant la
première requête, le routeur n’a jamais à deviner.
Reste une collision de noms tant qu’un préfixe est actif : un dossier de documentation nommé comme un dépôt ou une version. La compilation la rejette au lieu de la trancher silencieusement ; voir Ce que la compilation vérifie.
La version par défaut
Une ref par dépôt est servie sans préfixe de version : la première de la liste,
ou celle que nomme sourceOptions.defaultRef. C’est l’URL vers laquelle pointer
et celle vers laquelle les moteurs de recherche sont dirigés.
Où en est une version dans sa vie
status, sur une source ou une ref, est un cycle de vie et non un synonyme de
« est la version par défaut » : un site peut publier la v2 comme actuelle tandis
que la v1 est simplement plus ancienne et la v0 réellement morte, et le lecteur
doit savoir dans lequel des trois cas il se trouve.
| Statut | Ce qu’on dit au lecteur | Dans le sitemap |
|---|---|---|
upcoming | Cela peut encore changer — pas de conseil de MAJ | Seulement si par défaut |
current | Rien | Seulement si par défaut |
maintained | Une version plus récente existe | Seulement si par défaut |
deprecated | Une version plus récente existe ; mettez à jour | Seulement si par défaut |
eol | Cette version est morte | Jamais |
upcoming est le seul qui ne parle pas d’âge. Une version peut ne pas être
celle par défaut parce qu’elle n’a pas encore eu lieu, et dire à ce lecteur de
« mettre à jour » est exactement à l’envers. Semver ne peut pas situer une
branche face à un tag : ce cas est donc déclaré dans la configuration plutôt que
déduit.
À côté du bandeau, une page d’une version non par défaut porte noindex et un
canonical pointant vers la même page dans la version par défaut — sans quoi un
moteur de recherche servirait la v0.7.0 aussi volontiers que la documentation du
jour. Les deux moitiés vont ensemble : le bandeau est la visible, le link-rel
l’invisible, et l’une sans l’autre laisse un public dans l’erreur.
Quand une page manque dans une version
Le sélecteur ne propose qu’une version qui possède réellement la page, et le lien canonique se résout vers le chemin existant le plus proche. Une URL qui ne résout vers rien reçoit un 404 qui suggère la page la plus proche dans la navigation — on rate facilement une URL versionnée d’un segment, et un 404 vide laisse le lecteur sans rien à cliquer.