Quellen

Eine Quelle ist ein Ordner mit Markdown: in diesem Repository oder in einem anderen, am aktuellen Checkout oder an benannten Refs. Die sources-Liste ist der einzige Ort, an dem sie deklariert werden, und alles andere wird daraus erzeugt.

sources: [
  { path: 'docs', slug: 'acme' },
  { repo: 'acme/api', path: 'docs', refs: ['main', 'v2.0.0', 'v1.4.0'] }
]

Zwei Repositories und drei Refs: fünf Collections, die URL-Präfixe, die sie bedienen, ein Versionsumschalter, die Weiterleitungsregeln und die Sitemap-Einträge. Nichts davon wird von Hand geschrieben. Jedes Feld steht in der Quellen-Referenz.

#Wie es funktioniert

Content v3 erledigt bereits die schwierigere Hälfte. Eine Collection-Quelle nimmt eine Repository-URL, einen Branch oder Tag und Zugangsdaten entgegen, und Content lädt sie herunter und speichert sie nach Hash zwischen — mehrere Repositories, private Repositories und das Lesen von einem Tag gibt es dort alles. duxt baut nichts davon nach.

Was duxt hinzufügt, passiert beim Laden der Konfiguration. content.config.ts ist ausgeführter Code und keine Datendatei, kann also die app.config.ts der Seite lesen und seine Collections aus dieser Liste berechnen — eine Collection je Repository × Ref, jede mit absolutem cwd, einem aus dem Slug abgeleiteten Namen und dem Seitenschema, das das Theme braucht. Dieselbe Liste wird vom Build ein zweites Mal aufgelöst, zum Manifest: welche Collection welches URL-Präfix bedient, welcher Ref der Standard ist, woher jede Seite kam. Dieses Manifest liest das Theme, und es wird als resolvedSources in die App-Konfiguration zurückgeschrieben.

#Warum es so gebaut ist

Collections von Hand zu deklarieren skaliert nicht in genau der Richtung, in der Dokumentation tatsächlich wächst: drei Versionen über vierzehn Repositories sind zweiundvierzig Deklarationen, und jedes Release bearbeitet alle vierzehn. Die Kurzform hält die Liste so lang wie die Zahl der Projekte.

Der Preis ist, dass eine Quellenliste weniger ausdrücken kann als eine von Hand geschriebene Collection. Das ist ein bewusster Handel: Wer etwas braucht, das die Kurzform nicht sagen kann, schreibt eine eigene content.config.ts und übernimmt vollständig — denn Content führt die Datei aus jeder Ebene zusammen, wobei die spätere gewinnt.

#Was dabei abfällt

Weil eine Quelle ein Repository, einen Ref und einen Ordner benennt, brauchen mehrere Funktionen keine eigene Konfiguration: „Diese Seite bearbeiten“, das Datum der letzten Änderung und die Mitwirkendenliste werden alle daraus abgeleitet. Die Historie einer entfernten Quelle zu lesen kostet einen vollständigen Clone, deshalb wartet das auf history: true — ein flacher Clone würde für jede Datei den Autor der Spitze melden, und das sind falsche Daten statt fehlender.