URLs und Versionen

Jede Seite wird ausgeliefert unter

/[repo]/[version]/[...pfad]

wobei beide Präfixe optional sind — und die Entscheidung, ob eines davon erscheint, fällt zur Build-Zeit aus der Quellenliste, nie pro Anfrage.

• Ein Repository-Segment erscheint, sobald es mehr als ein Repository gibt, wenn showRepo es erzwingt oder — dann nur für diese eine Quelle — wenn die Quelle einen eigenen slug nennt.
• Ein Versionssegment erscheint, sobald eine Quelle mehr als einen Ref veröffentlicht, oder wenn showVersion es erzwingt.

Ein einzelner unversionierter Ordner liefert also /guides/deploying aus, und nichts in der URL verrät, dass Repositories und Versionen überhaupt existieren.

#Warum die Präfixe zur Build-Zeit entschieden werden

Wären beide Präfixe pro Anfrage optional, wäre das erste Segment mehrdeutig: /guides/… könnte ein Ordner, ein Repository oder eine Version sein, und erst das Nachschlagen aller drei würde es klären. Weil die Form einer URL vor der ersten Anfrage feststeht, muss der Router nie raten.

Was bleibt, ist eine Namenskollision, solange ein Präfix aktiv ist — ein Doku-Ordner, der wie ein Repository oder eine Version heißt. Der Build weist das zurück, statt es stillschweigend in eine Richtung aufzulösen; siehe Was der Build prüft.

#Die Standardversion

Ein Ref je Repository wird ohne Versionspräfix ausgeliefert: der erste in der Liste, oder der, den sourceOptions.defaultRef benennt. Das ist die URL zum Verlinken und die, auf die Suchmaschinen gelenkt werden.

#Wo eine Version in ihrem Leben steht

status an einer Quelle oder einem Ref ist ein Lebenszyklus, kein Synonym für „ist die Standardversion“ — eine Seite kann v2 als aktuell veröffentlichen, während v1 bloß älter und v0 wirklich tot ist, und dem Leser muss gesagt werden, in welchem der drei Fälle er sich befindet.

upcoming ist das eine, bei dem es nicht ums Alter geht. Eine Version kann abseits des Standards liegen, weil sie noch nicht stattgefunden hat, und diesem Leser „aktualisiere“ zu sagen ist genau verkehrt herum. Semver kann einen Branch nicht gegen einen Tag einordnen, deshalb wird dieser Fall in der Konfiguration angegeben statt abgeleitet.

Neben dem Banner trägt eine Seite in einer Nicht-Standardversion noindex und ein canonical, das auf dieselbe Seite in der Standardversion zeigt — sonst liefert eine Suchmaschine v0.7.0 ebenso wahrscheinlich aus wie die heutige Dokumentation. Die beiden Hälften gehören zusammen: das Banner ist die sichtbare, das Link-Rel die unsichtbare, und jede allein lässt eine Zielgruppe im Irrtum.

#Wenn eine Seite in einer Version fehlt

Der Umschalter bietet nur eine Version an, die die Seite tatsächlich hat, und der Canonical-Link löst auf den nächstgelegenen existierenden Pfad auf. Eine URL, die auf nichts auflöst, wird mit einem 404 beantwortet, der die nächste Seite aus der Navigation vorschlägt — versionierte URLs verfehlt man leicht um ein Segment, und ein leerer 404 lässt den Leser ohne Ziel zum Klicken.