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 one YAML value. !import-list flattens the YAML lists in a directory, while !import-map maps each YAML filename stem in a directory to its value. Paths are first resolved relative to the file containing the tag, then relative to the directory containing site.toml. Included YAML can contain nested includes. Inclusion happens before validation.

Projects can register build plugins in site.toml. Each module exposes a build(config) hook returning PluginResult; hooks run after static assets are copied and can derive build-only artifacts from durable project data.

[site]
plugins = ["site_plugins.search"]

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.