Generierte Sektionen

Eine Quelle veröffentlicht das Markdown, das ein Repository hält. Eine generierte Sektion veröffentlicht etwas, das überhaupt kein Markdown ist: Eine Quelle nennt ein Artefakt und den Typ, der es liest, und die Seiten folgen daraus.

{
  path: 'docs',
  generated: [
    { type: 'changelog', path: 'CHANGELOG.md', label: 'Releases' },
    { type: 'openapi', path: 'openapi.yaml', label: 'API' }
  ]
}

Zwei Typen bringt die Ebene mit — changelog und openapi — und die Registry ist offen, eine Site kann also eigene hinzufügen oder einen davon ersetzen. Die Felder, die eine Deklaration nimmt, sind für jeden Typ dieselben und stehen in Quellen.

#Die Seiten sind eine gewöhnliche Collection

Das ist der ganze Punkt, und er ist es wert, klar gesagt zu werden: Was ein Typ erzeugt, sind Markdown-Dateien, geschrieben in eine Collection, die Content wie jede andere baut. Also findet die Suche sie, llms.txt listet sie, die Sitemap trägt sie, der Versionsumschalter bewegt sich zwischen ihnen, und die Kopieren-Schaltfläche reicht einem Modell die Seite.

Nichts hier ist ein zweiter Rendering-Pfad. Ein Typ, der der Suche etwas über sich beibringen müsste, oder dem Feed, oder der Sitemap, wäre eine parallele Site innerhalb der Site — und jede dieser Nahtstellen ist ein Ort, an dem die beiden Hälften auseinanderlaufen.

#Was einem Typ gehört, und was nicht

Ein Typ beantwortet drei Fragen und sonst nichts: wie sein Artefakt in Seiten zerfällt, und die zwei Richtlinien unten. Er entscheidet nicht, wohin sein Eintrag in der Navbar geht, wie die Sektion heißt oder welches Artefakt er liest — das gehört der Deklaration, weil es der Site gehört.

#Versionierung

Die beiden sind Gegensätze, und beide sind richtig. Eine API-Beschreibung gehört zu dem Release, das sie beschreibt: Einem Leser auf v1, der fragt, was ein Feld bedeutet, darf nicht die Antwort von v2 gezeigt werden. Ein Changelog ist das Umgekehrte — es ist kein Dokument pro Version, das zufällig andere Versionen erwähnt, es ist die Liste der Versionen, und eine Kopie pro Version würde dieselbe Datei unter drei URLs veröffentlichen, jede ohne die Releases, die danach kamen.

Dass derselbe Mechanismus beides erzeugt, ist der Grund, warum Versionierung eine Richtlinie des Typs ist und keine Regel der Ebene.

#Lokalisierung

Ein per-locale-Typ liest die locales-Zuordnung der Deklaration — ein Artefakt pro Sprache, weil eine übersetzte OpenAPI-Beschreibung ein echtes Artefakt ist und nicht dieselbe Datei mit neuem Etikett. Eine Locale, die die Zuordnung nicht nennt, baut nichts, und das ist Absicht: Die vorhandene Fallback-Kette liefert ihr dann die Standardsprache, und der Übersetzungshinweis sagt es. Für jede Locale ein Artefakt zu deklarieren und still dieselbe Datei unter jeder auszuliefern würde diesen Hinweis verstummen lassen und den Leser ahnungslos.

Ein original-Typ überspringt die Zuordnung ganz. Ein Release-Log wird einmal geschrieben, vom Release-Werkzeug, in der Sprache, in der das Projekt committet — eine lokalisierte Site liefert also das Original und sagt es mit dem Hinweis, den sie ohnehin zeichnet.

#Wo sie scheitern

Ein lokales Artefakt, das fehlt, unlesbar ist oder eine Option bekommt, die sein Typ nicht kennt, lässt den Build beim Laden der Konfiguration scheitern — die eigene Konfiguration der Site ist ein Fehler, den der Build nicht tragen darf, und eine Sektion, die still leer wurde, ist eine Sektion, deren Fehlen niemand bemerkt.

Was bleibt, ist entweder ein entferntes Artefakt, das zwischen zwei Releases legitim veraltet sein kann, oder eine Seite, die mit etwas Fehlendem gerendert hat. Das sind Warnungen im Build-Bericht — siehe Was der Build prüft.