Site generator content format

Every _<name>.yaml file below content/ is a render manifest. The part after the underscore determines the default output basename; the selected template determines its suffix. For example, _index.yaml with page.html writes index.html, while _feed.yaml with feed.xml writes feed.xml.

A manifest selects its validation model and default template with $schema:

$schema: ../../schemas/pages/page.json
body:
  - !import introduction.yaml
  - !import resources.yaml

!import inserts a mapping, while !import-list inserts a sequence. Their paths are relative to the file containing the tag, and included YAML can contain nested includes. Inclusion happens before the assembled value is validated.

A schema declares its stable generated path and default template through the public API:

from site_generator import Schema, schema

@schema("pages/example", template="example.html")
class Example(Schema):
    title: str

A manifest can override rendering without changing schema selection:

$schema: ../../schemas/pages/example.json
$template: compact.html
$output: summary.txt

$template overrides the schema default. $output is optional and overrides the inferred filename; it must remain relative to the manifest directory.

site_generator.dataset.YamlDataset lets separately invoked update tools validate generated YAML with the same Pydantic models used by manifests. It provides deterministic serialization, generated-file headers, atomic replacement, and a non-writing check mode. Fetching and adapting external sources remains the responsibility of the update tool.

Development server

Run site-generator develop (or make dev) to build the site, serve it at http://localhost:1313, and rebuild when content, schemas, templates, assets, or the configuration file changes. Use --host, --port, and --interval to override the defaults.