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' },
    { type: 'bruno', path: 'bruno', label: 'Requests' }
  ]
}

Drei generierte Typen bringt die Ebene mit — changelog, openapi und bruno — und die Registry ist offen, eine Site kann also eigene hinzufügen oder einen davon ersetzen. Die Felder stehen in Quellen.

tfplugindocs liegt daneben, ist aber bewusst kein vierter generierter Typ: Es ist ein Quellen-Dialekt für einen bereits vorhandenen Markdown-Baum. Generierte Typen verwandeln ein anderes Artefakt in Markdown-Seiten; ein Dialekt erklärt duxt die Struktur von Markdown, das schon existiert.

#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

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 aus demselben Grund pro Version — jede Version hat ihre eigene CHANGELOG.md ausgeliefert, und wer die Version wechselt, bleibt im Changelog, statt auf eine Übersicht geschickt zu werden. global bleibt für einen Typ, dessen Artefakt wirklich eine einzige Historie unter einer versionsneutralen URL ist.

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.