Generated sections

A source publishes the Markdown a repository holds. A generated section publishes something that is not Markdown at all: a source names an artefact and the type that reads it, and the pages follow.

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

Three generated types ship with the layer — changelog, openapi and bruno — and the registry is open, so a site can add its own or replace one of these. The fields a declaration takes are the same whichever type reads it, and they are in Sources.

tfplugindocs is adjacent but deliberately not a fourth generated type: it is a source flavour for an already-Markdown tree. The distinction keeps one rule honest — generated types turn another artefact into Markdown pages, while a flavour teaches duxt the structure of Markdown that already exists.

#The pages are an ordinary collection

This is the whole point, and it is worth stating plainly: what a type produces is Markdown files, written into a collection Content builds like any other. So the search finds them, llms.txt lists them, the sitemap carries them, the version switcher moves between them, and the copy control hands a model the page.

Nothing here is a second rendering path. A type that had to teach the search about itself, or the feed, or the sitemap, would be a parallel site inside the site — and every one of those seams is a place for the two halves to drift.

#What a type owns, and what it does not

A type answers three questions and nothing else: how to split its artefact into pages, and the two policies below. It does not decide where its entry goes in the navbar, what the section is called, or which artefact it reads — those belong to the declaration, because they belong to the site.

#Versioning

An API description belongs to the release it describes: a reader on v1 asking what a field means must not be shown v2's answer. A changelog is per version for the same reason — each version shipped its own CHANGELOG.md, and a reader who changes versions stays in the changelog instead of being sent to an overview. global remains for a type whose artefact genuinely is one history at one version-neutral URL.

That the same mechanism produces both is why versioning is a policy of the type rather than a rule of the layer.

#Localisation

A per-locale type reads the declaration's locales map — an artefact per language, because a translated OpenAPI document or Bruno collection is a real artefact and not the same input relabelled. A locale the map does not name builds nothing, which is deliberate: the existing fallback chain then serves it the default language and the translation banner says so. Declaring an artefact for every locale and quietly serving the same file under each would leave that banner silent and the reader unaware.

An original type skips the map entirely. A release log is written once, by the release tool, in whatever language the project commits in — so a localised site serves the original and says so with the banner it already draws.

#Where they fail

A local artefact that is missing, unreadable, or handed an option its type does not know fails the build while the config is loading — the site's own configuration is a mistake the build must not carry, and a section that silently became empty is a section nobody notices is gone.

What is left is either a remote artefact, which may legitimately have gone stale between one release and the next, or a page that rendered with something missing from it. Those are warnings in the build report — see What the build checks.