Zum Inhalt springen
duxt

Mehrere Versionen

Dieselbe Dokumentation an mehreren Refs ausliefern, mit Umschalter und Banner.

Ein Ref wird zu einer Version. Richte eine Quelle auf Tags, und jeder davon wird veröffentlicht — mit einem Versionssegment in der URL und einem Eintrag im Umschalter.

Schritte

  1. Liste die Refs auf. Eine bloße Zeichenkette ist ein Branch. Ein Tag muss das sagen — git hält beide in getrennten Namensräumen, und einen Tag unter refs/heads anzufragen lässt den Build scheitern.
    sources: [
  {
    repo: 'acme/api',
    path: 'docs',
    refs: [
      { branch: 'main', status: 'upcoming' },
      { tag: 'v2.0.0' },
      { tag: 'v1.4.0' },
      { tag: 'v0.9.0', status: 'eol' }
    ]
  }
],
sourceOptions: { defaultRef: 'v2.0.0' }
  2. Benenne den Standard. defaultRef ist der Ref, der ohne Versionspräfix ausgeliefert wird, und der, auf den Suchmaschinen gelenkt werden. Ungesetzt ist es der erste in der Liste — was selten das ist, was du willst, wenn die Liste mit einem Branch beginnt.
  3. Gib den Lebenszyklus an, wo er sich nicht ableiten lässt. Semver ordnet Tags, „älter als der Standard“ braucht also keine Hilfe. Einen Branch gegen einen Tag kann es nicht einordnen: main ist upcoming, und ohne diese Angabe wird seinem Leser gesagt, er solle auf eine Version aktualisieren, die älter ist als das, was er liest.
  4. Nimm latest, wenn du diese Liste nicht bei jedem Release bearbeiten willst. Es löst zur Build-Zeit auf den neuesten Semver-Tag dieses Repositories auf.
    refs: [{ branch: 'main', status: 'upcoming' }, 'latest']
  5. Markiere die Versionsanforderung einer Seite im Text, wo ein Leser, der eine Version ansieht, die anderen nicht sehen kann:
    ### Wiederholungen :since{version="v2.0.0"}

Was mit den alten Versionen passiert

Eine Nicht-Standardversion trägt noindex und ein canonical, das auf dieselbe Seite in der Standardversion zeigt, und eine eol-Version verlässt die Sitemap vollständig. Das hindert eine Suchmaschine daran, v0.9.0 anzubieten, wo der Leser die heutige Dokumentation wollte — siehe URLs und Versionen.

Checkliste

  • Jeder Tag ist als { tag: … } geschrieben, nicht als bloße Zeichenkette
  • defaultRef benennt die Version, auf der Leser landen sollen
  • Ein Branch in der Liste trägt einen ausdrücklichen status
  • Der Umschalter zeigt jede Version, mit einem Abzeichen an den toten
  • Die Seite einer toten Version fehlt in /sitemap.xml
War diese Seite hilfreich?