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

Global. Eine Historie, aus der Standardversion gelesen, unter einer versionsneutralen URL ausgeliefert, mit unterdrücktem Umschalter.

Ein Changelog ist kein Dokument pro Version, das zufällig andere Versionen erwähnt — es ist die Liste der Versionen. Eine Kopie pro Version würde dieselbe Datei unter drei URLs veröffentlichen, jede ohne die Releases, die danach kamen, und einem Leser, der zufällig auf v1 landet, würde erzählt, das Projekt sei dort stehen geblieben.

#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 — und bei einer global-Sektion gibt es ohnehin nur eine Historie. 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.