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' }
  ]
}

Two types ship with the layer — changelog and openapi — 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.

#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

The two are opposites, and both are right. 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 the reverse — it is not a per-version document that happens to mention other versions, it is the list of the versions, and building one copy per version would publish the same file under three URLs, each missing the releases that came after it.

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 description is a real artefact and not the same file 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.