Die Sektion deklarieren

Eine Release-Historie ist eine generierte Sektion: Eine Quelle nennt die Datei und den Typ, der sie liest, und die Seiten folgen daraus.

export default defineAppConfig({
  duxt: {
    sources: [
      {
        path: 'docs',
        generated: [
          {
            type: 'changelog',
            path: 'CHANGELOG.md',
            label: 'Releases'
          }
        ]
      }
    ]
  }
})

Die Felder, die eine Deklaration nimmt, sind für jeden Typ dieselben und stehen in Quellen. changelog nennt eine eigene Option — granularity — und beantwortet die zwei Richtlinien unten.

#Versionierung

Pro Version. Jede veröffentlichte Dokumentationsversion bekommt einen eigenen Changelog, gelesen aus der CHANGELOG.md dieser Version und innerhalb von ihr ausgeliefert — /releases für die Standardversion, /v2.x/releases neben /v2.x/guides. Das funktioniert genau wie die Dokumentation und die API-Referenz daneben.

Jede Kopie zeigt die ganze Datei, die diese Version mitgebracht hat, frühere Releases eingeschlossen — der Changelog einer älteren Version endet also dort, wo diese Version endete. Der Versionsumschalter hält den Leser im Changelog: Auf einer Release-Seite öffnet er dasselbe Release in der anderen Version, und wo diese Version das Release nie hatte, öffnet er ihre Changelog-Übersicht statt einer fehlenden Seite.

Die Datei ist in jeder Version Pflicht. Eine veröffentlichte Version ohne CHANGELOG.md lässt den Build fehlschlagen, bei einer heruntergeladenen Quelle genauso wie beim gebauten Repository — die Version wegzulassen oder dort die Historie einer anderen Version zu zeigen, würde beides etwas veröffentlichen, das diese Version nie ausgeliefert hat.

#Lokalisierung

Das Original, in jeder Sprache. Eine Collection, gebaut aus der Standard-Locale.

Ein Release-Log wird einmal geschrieben, vom Release-Werkzeug, in der Sprache, in der das Projekt committet. Daran ist nichts pro Locale, eine lokalisierte Site liefert also das Original und sagt es mit dem Übersetzungshinweis, den sie für eine unübersetzte Seite ohnehin zeichnet. Die locales-Zuordnung der Deklaration wird nur von per-locale-Typen gelesen und tut hier nichts.

#Wohin der Eintrag geht

navigation: 'sections' ist der Standard und stellt den Eintrag in die Sektionsreihe — die obersten Teile der Dokumentation.

Ein Release-Log ist oft keiner davon: Es ist etwas, das das Projekt neben seiner Dokumentation hat, und nicht ein Teil von ihr. navigation: 'navigation' verschiebt den Eintrag in die schmale erste Reihe, und false stellt ihn nirgendwohin und überlässt es der Site, ihn zu verlinken.

{
  type: 'changelog',
  path: 'CHANGELOG.md',
  label: 'Releases',
  navigation: 'navigation'
}

#Der Feed

duxt.feed.path benennt die Sektion, aus der /rss.xml gebaut wird, und eine Release-Historie ist das, wofür er geschrieben wurde: Jede Release-Seite trägt das eigene date des Releases, und ein Release ist etwas, das passiert ist — was eine bearbeitete Referenzseite nicht ist.

feed: { path: '/releases', title: 'mein Projekt — Releases' }

Aus, solange der Schlüssel nicht gesetzt ist. Nur die Standardversion jeder Quelle trägt bei, eine versionierte Site wiederholt also nicht jeden Eintrag einmal pro Version, obwohl jede Version ihren eigenen Changelog veröffentlicht. Siehe Konfiguration und /rss.xml.

#Wenn die Datei nicht gelesen werden kann

Eine lokale Datei, die nicht da ist, lässt den Build beim Laden der Konfiguration scheitern, wie bei jedem Typ. Was die Datei nicht ganz sagt — eine Überschrift, die wie ein Release aussieht, aber nicht als eines gelesen wird — ist stattdessen eine Warnung im Build-Bericht; siehe Was gelesen wird und Was der Build prüft.