Quellen

duxt.sources ist eine Liste von Quelleneinträgen; duxt.sourceOptions sagt, wie daraus URLs werden. Beide werden zur Build-Zeit gelesen. Was sie erzeugen und warum, steht in Quellen.

#Ein Quelleneintrag

Zwei Felder sind leicht zu verwechseln und teuer, wenn man sie falsch setzt:

• repo lädt herunter, origin verlinkt nur. Das eigene Repository in repo zu nennen lässt den Build den Checkout klonen, in dem er bereits steht.
• history kostet einen vollständigen Clone. Content klont ein entferntes Repository mit --depth 1, sein Checkout hält also einen Commit und jede Datei sieht aus, als hätte sie die Person geschrieben, die die Spitze gesetzt hat — falsche Daten, keine fehlenden. Das einzuschalten macht den Clone einmal vollständig. Eine von der Platte gelesene Quelle ist ohnehin ein vollständiger Checkout und wird unabhängig davon gelesen.

slug beansprucht ein Segment. Ein Segment bekommt eine Quelle sonst erst, wenn die Liste mehr als ein Repository nennt — alles oder nichts, für die ganze Seite. Eine Quelle, die einen eigenen slug schreibt, wird ohnehin darunter ausgeliefert, und die Quellen ohne bleiben, wo sie sind. Genau das lässt eine Sache unter /demo neben einer Dokumentation stehen, die die Wurzel behält.

#Refs

Eine bloße Zeichenkette ist ein Branch. Ein Tag muss das sagen: git hält Branches und Tags in getrennten Namensräumen, und einen Tag unter refs/heads zu verlangen lässt den Build mit Could not find refs/heads/… scheitern.

refs: [
  'main',                                     // ein Branch
  { branch: 'next', status: 'upcoming' },     // derselbe, mit einem Lebenszyklus
  { tag: 'v2.0.0', label: 'v2' },             // ein Tag
  'latest'                                    // der neueste Semver-Tag, im Build aufgelöst
]

'latest' ist reserviert. Ein Branch, der wirklich latest heißt, braucht die Form { branch }.

#Locales

Weggelassen hat die Quelle eine Sprache und eine Collection. Aufgelistet wird jeder Eintrag zu einer eigenen Collection.

locales: [
  'en-GB',                                              // der Standard: docs/ selbst
  'de',                                                 // docs/de/
  { locale: 'fr', path: 'translations/fr' },            // woanders in diesem Repository
  { locale: 'es', repo: 'acme/docs-es', path: 'docs' }  // ein anderes Repository
]

Eine Zeichenkette ist ein Ordner innerhalb des path der Quelle. Die Objektform überschreibt path, repo und ref allein für diese Sprache — und genau das lässt eine Übersetzung in einem eigenen Repository leben, mit eigenen Betreuern und eigenem Releaseplan.

Die Standard-Locale ist der Baum in path selbst und nimmt keinen Ordner. Welche das ist, kommt aus sourceOptions.defaultLocale, und sie muss mit i18n.defaultLocale übereinstimmen — der Build scheitert, wenn sie abweichen, denn content.config.ts löst die Collections ohne Zugriff auf die Nuxt-Konfiguration auf.

Ein Ref darf eigene locales tragen, die die der Quelle überschreiben, genau wie status. Das ist die übliche Form: Die aktuelle Version ist übersetzt, die dahinter nicht.

refs: [
  { tag: 'v2.0.0' },                     // erbt die Locales der Quelle
  { tag: 'v1.0.0', locales: ['en-GB'] }  // nur das Original
]

Benenne einen Ordner nach der Sprache, wo eine Region nichts hinzufügt: docs/pt/ bedient sowohl pt-PT als auch pt-BR, weil eine Seite über ihre Basissprache zurückfällt. Dieselbe Regel, der die Locale-Dateien der Ebene folgen.

#Status

Was jeder Wert eine Seite kostet, steht in URLs und Versionen.

#Generierte Sektionen

generated listet Artefakte auf, die kein Markdown sind, und den Typ, der jedes davon zu Seiten liest. Was der Mechanismus ist und welche zwei Richtlinien ein Typ beantwortet, steht in Generierte Sektionen; die Felder unten sind dieselben, welcher Typ sie auch liest.

path ist ein Pfad und nie eine URL. Bei einer Quelle, die Content klont, ist er relativ zur Wurzel dieses Checkouts — das Artefakt reist also mit der Version, zu der es gehört, eine Regel in beide Richtungen. Ein beliebiger Ort würde erlauben, ein Artefakt von überall zu holen, und die Frage nach Netzwerk zur Build-Zeit wieder öffnen, die sources bereits geschlossen hat.

label ist eine einfache Zeichenkette und kein übersetzter Text, aus demselben Grund, aus dem das Label einer Version einer ist: Ein übersetzter Text ist keine stabile URL.

options ist für alles außer dem Typ, der sie liest, undurchsichtig — eine Granularität bedeutet einem Changelog etwas und einer API-Referenz nichts. Ein Schlüssel, den der Typ nicht kennt, lässt den Build scheitern, statt ignoriert zu werden: Eine falsch geschriebene Option ist eine Site, die still nicht bekommt, was sie konfiguriert hat.

#Quellenoptionen

#Das aufgelöste Manifest

Der Build macht aus der Liste oben duxt.resolvedSources, und das ist es, was das Theme liest. useDuxtCollection() legt es offen; jeder Eintrag trägt den Collection-Namen, das URL-prefix, repo, version, isDefault, locale, isDefaultLocale, status, das Repository und den Ref, aus denen die Seiten kamen, und ob seine history gelesen wurde.

Der Locale fehlt bewusst im prefix: i18n stellt ihn dem Pfad ohnehin voran, jede Sprache einer Quelle teilt sich also ein Präfix und unterscheidet sich nur durch die Collection.