Site generation

Overview

sitegen builds a static directory from Markdown, routes, exports, reports, and local assets. It is executable and does not create a queryable data node.

Example configuration

site:
  title: My site              # Required: example site title.
  base_url: /                 # Default: serve at the domain root.
  home_url: null              # Default: Home links use base_url.
  site_url: null              # Default: no canonical URL for RSS.
  github_url: null            # Default: no repository link.
  default_range: null         # Default: no configured chart range.
routes:                      # Default: []; this example supplies a home page.
  - name: home               # Required for this route: example name.
    type: static             # Required: select the static-page variant.
    slug: ""                 # Required: empty slug produces index.html.
    page: /site/index.md      # Required for a useful static route; default null.
    export: null             # Default: no export stage.
    annotations: null        # Default: no secondary annotation export.
    content: null            # Default: no content stage.
    routes: []               # Default: no child routes.
content: []                  # Default: no Markdown discovery stages.
exports: []                  # Default: no dataset exports.
partials: {}                 # Default: no shared Markdown partials.
static: []                   # Default: no extra copied assets.
sidebar: []                  # Default: no configured navigation entries.
labels: {}                   # Default: no display-name overrides.
metric_registry: {}          # Default: no metric instrument-kind overrides.
metric_captions: {}          # Default: no chart-caption overrides.
reports: {}                  # Default: no named reports.
theme: {}                    # Default: built-in CSS variables.
subsites: []                 # Default: no imported subsites.
analytics: null              # Default: no reported page-view instrumentation.
documentation: null         # Default: ordinary site rendering.
strict: false                # Default: strict diagnostics not enabled.
feed: null                   # Default: no RSS feed.
explore: null                # Default: no browser data explorer.
status_grid: null            # Default: no pond status grid.
footer: null                 # Default: no custom footer text.
header: null                 # Default: no header image.

This includes every top-level field and every field of the selected static route. Empty collections and null values mean those optional features are disabled; they are not placeholders for required values. The home route is an intentional override of the empty default. Create /site/index.md in the selected input root before building. The full reference below describes the nested configuration when enabling exports, reports, feeds, or other features.

Use and behavior

Install with pond mknod sitegen /etc/site --config-path site.yaml, then run pond run /etc/site -- build OUTPUT --strict. The same YAML can run without a pond using pond run -d SOURCE host+sitegen:///site.yaml -- build OUTPUT --strict.

Paths are rooted in the selected input filesystem, not the YAML file's directory. See the configuration topics, blog guide, and timeseries-site guide.

Optional reported page views

Instrumentation is disabled by default. To prepare an instrumented build:

analytics:
  enabled: true
  site_id: caspar-water
  endpoint: /_analytics/view
  default_section: Static content
  sections:
    /blog: Blog
    /data: Monitoring
    /analysis: Monitoring
    /septic: Monitoring
    /explore: Monitoring
  exclude:
    - /status

Use the existing web server to record beacons in a dedicated, privacy-filtered log, separate from ordinary access logs. The script sends a bodyless POST to the configured endpoint with URL-encoded page_uri and catalog_id query parameters. These are publisher metadata, not the current browser URL. The endpoint should return HTTP 204 with Cache-Control: no-store; a successful response is not a durable-journal acknowledgement or proof of a human visit. Do not publish an enabled build until log routing, privacy filtering, and periodic ingestion into the owning pond are configured. The script makes one best-effort request per top-level document, at first visibility after prerender activation. Tab returns and already-reported back/forward-cache restores do not report again; reloads create new documents. Failures warn without blocking the page, and there are no retries, cookies, visitor identifiers, client timestamps, or referrers in the request.

Each enabled site emits _analytics/catalog.json, _analytics/pages.parquet, and one shared _analytics/view-<sha256>.js asset in its own output directory. The catalog contains version 2, stable site_id, sorted entries (page_uri, title, aliases, section), and a SHA-256 identity derived from version, site identity, and entries serialized as compact JSON in that field order. Neither build timestamps nor exported data change its identity. Public catalog labels describe only eligible pages. The web server does not need an installed catalog registry. Beacon page and catalog identities remain untrusted claims, not server-validated membership.

Sections are publisher-owned labels. sections maps site-relative path prefixes to labels, matching whole path segments; the longest matching prefix wins. Prefixes start with / and, except for /, have no trailing slash. default_section applies to eligible pages without a match and defaults to Other / unclassified. A prefix /blog matches /blog/entry, not /blogger. Mount prefixes are stripped before matching. Subsites do not inherit the parent's section rules; Noyo can use default_section: Noyo and an empty sections map. Changing an emitted section changes the catalog identity.

The Parquet inventory contains one row per eligible canonical page, with only site_id, page_uri, and section, all non-null UTF-8 strings. After publishing, copy it into the owning analytics pond with ordinary pond copy host:///..., as a current versioned data file, not host+table or host+series. Query it through file+table:///analytics/pages.parquet to read only the current file. It is a publisher inventory, not observations or a host-only report database. Unknown paths can then be grouped as Other / unclassified without exposing their names. An empty inventory is a valid zero-row Parquet file with the same schema: it replaces previous classifications, so all retained views become Other. Missing or unreadable inventory is an error, not a known-empty inventory.

Canonical paths include site.base_url exactly once. With the supported Caddy try_files {path} {path}.html {path}/ configuration, water.html identifies /water, while section/index.html identifies /section/. Explicit aliases include those emitted paths and the directory's slashless request path. Ambiguous serving paths fail enabled builds rather than merging page counts. The _analytics/ output namespace is reserved for generated analytics artifacts.

Subsites must opt in independently and use distinct site_id values and beacon endpoints, each routed to its own Caddy log. Parent enablement is never inherited, and no subsite entries enter the parent's catalog. A subsite's configured base_url must match its actual publishing mount. Noyo therefore remains its own site while mounted at /noyo-harbor/; a later domain move leaves its stable site identity unchanged but changes its catalog paths. The endpoint is always an origin-relative path, never mount-prefixed.

Use frontmatter analytics: false or exact canonical paths in exclude for private, diagnostic, or synthetic pages. Navigation hidden is unrelated. The site's /analytics dashboard (including its directory form) is excluded by default. Raw HTML inside Markdown is instrumented by the surrounding layout. Copied standalone HTML assets must be explicitly excluded or converted to layout-rendered pages; they are never silently counted as instrumented.

Documentation configurations remain off unless explicitly enabled. build --no-analytics suppresses instrumentation on rendered pages, including independent subsites; --quick also suppresses it on pages it renders. Quick builds leave skipped pages untouched in reused output directories and warn if output HTML still contains Sitegen's analytics tag. Use a fresh output directory for an analytics-free preview. These controls do not disable unrelated chart or page scripts.

Analytics publication boundary

The browser instrumentation does not publish an analytics report. Ingest the dedicated Caddy logs through ordinary logfile-ingest and query them through jsonlogs:// and SQL-derived nodes in the owning pond. Sitegen's ordinary reporting/export facilities are the integration boundary; public analytics report integration is pending.

The disclosure contract remains daily per-page counts and daily site totals over 30 UTC calendar days, including today. Reports must not expose raw events, hourly detail, or catalog identities. Missing observations are not zero, and maximum event time does not establish collection uptime or publication freshness. Coverage stays unknown unless independently established.

The former standalone collector, custom rollup/table factories, and host-state analytics_report setting and refresh command have been removed. There is no replacement host report directory or application-owned cache.

Full configuration

Settings

FieldAccepted typeRequiredDefaultDescription
analyticsAnalytics | nullnonullIndependent, opt-in reported page views. Never inherited by subsites.
contentarray of Content Stageno[]
documentationDocumentation | nullnonullOpt in to source-relative manual paths, literal code, and lean assets.
exploreExplore | nullnonullBrowser data explorer configuration. When present, the {{ explore }} shortcode (on an layout: explore page) exposes the named export stages as queryable datasets in a Datasette-style SQL playground. Opt-in per site: absent means the explorer falls back to the single export bound to the page's route.
exportsarray of Export Stageno[]
feedFeed | nullnonullRSS feed configuration. If present, an RSS feed is generated. Requires site.site_url to be set for absolute link generation.
footerstring | nullnonullCustom text shown in the page footer alongside the build identifier. Example: footer: "Made in Mendocino" renders as "Made in Mendocino | Watertown v0.39.0".
headerstring | nullnonullImage path for a full-width centered banner at the top of every page. Path is relative to base_url (e.g., "img/logo.svg"). If absent, no banner is rendered.
labelsmap of stringno{}Optional display-name overrides for template-route capture values. Keyed by the raw capture string (the $0/$1 value taken from the export path, e.g. DO), with the friendly label as the value (e.g. Dissolved Oxygen). Applied when a capture is rendered as a page title or heading via {{ $0 }}; URL slugs keep the raw value so links are unaffected. Missing keys fall back to the raw capture.
metric_captionsmap of stringno{}Optional human-readable caption per chart, keyed by <param>.<unit> (the same key used in metric_registry). When present, the dashboard renders the caption directly beneath the corresponding chart. Missing entries render no caption.
metric_registrymap of stringno{}Metric instrument-kind registry, keyed by metric name (the <param>.<unit> portion of a wide column name). Values are OpenTelemetry instrument kinds: counter, updowncounter, or gauge. Default kind is gauge; only non-gauge entries need to appear here. chart.js reads this map and applies a per-kind transform: counter -> first-difference per scope, plot rate updowncounter -> plot value as-is (today; future: sum across scopes for spatial aggregation) rate -> plot value as-is, but with a zero-anchored, always-rendered y-axis (for flow/rate gauges such as usage.gpm where 0 is meaningful) gauge / missing -> plot value as-is (latest/avg) The canonical source of truth for each project should be a Weaver semconv registry (e.g. caspar.water's config/semconv/watertown-pond.yaml); mirror its non-gauge entries here.
partialsmap of stringno{}
reportsmap of Reportno{}Named reports rendered from the same exported datasets as the site.
routesarray of Routeno[]
sidebararray of Sidebar Entryno[]Ordered list of sidebar entries. Each entry is either a plain string (matched by page title, preferring exact match) or a map with label and children for hierarchical navigation. When present, content_nav renders pages in this exact order. Pages not listed are excluded from the sidebar.
siteSite Metayesnot specified
staticarray of Static Assetno[]
status_gridStatus Grid | nullnonullOptional pond status grid configuration. When present, sitegen runs DataFusion queries against the configured journal data at render time and exposes per-unit status to the {{ pond_status_grid /}} shortcode as static HTML cards. See StatusGridConfig for fields.
strictbooleannofalseReject incomplete routes, navigation, includes, and local links.
subsitesarray of Subsiteno[]Sub-sites to generate recursively from imported ponds. Each sub-site references a sitegen config inside an imported mount and generates into a subdirectory of the output.
thememap of stringno{}Theme overrides for CSS custom properties. Any key here overrides the corresponding CSS variable in :root. Example: accent: "#1a365d" sets --accent: #1a365d.

Analytics

First-visible-document analytics, disabled unless explicitly enabled.

FieldAccepted typeRequiredDefaultDescription
default_sectionstringno"Other / unclassified"Section assigned to eligible pages without a matching section prefix.
enabledbooleannofalse
endpointstringno"/_analytics/view"Same-origin absolute path, routed to this site's dedicated beacon log.
excludearray of stringno[]Exact canonical mounted paths to exclude, in addition to /analytics. Frontmatter analytics: false also excludes a page; hidden does not.
sectionsmap of stringno{}Site-relative path prefixes mapped to section labels; longest match wins. Prefixes match complete path segments, independently of the publishing mount.
site_idstringyesnot specifiedStable publisher-owned site identity, independent of host and mount path.

Content Stage

A content stage: globs markdown data files in the pond and reads their frontmatter for metadata (title, weight, slug).

FieldAccepted typeRequiredDefaultDescription
namestringyesnot specifiedName referenced by content routes (e.g., "pages")
patternstringyesnot specifiedPond glob pattern matching data files (e.g., "/pages/*.md")

Documentation

Bounded documentation capabilities; paths are relative to the input root.

FieldAccepted typeRequiredDefaultDescription
include_rootsarray of stringno[]Approved directories for literal source inclusions.
source_rootstringyesnot specifiedMarkdown root used to derive nested slugs (excluding _generated).
versionintegeryesnot specifiedRequired renderer contract. Unsupported revisions fail explicitly. Constraints: format="uint32"; minimum=0.

Explore

Browser data explorer configuration.

FieldAccepted typeRequiredDefaultDescription
datasetsarray of Explore Datasetyesnot specifiedDatasets exposed in the explorer, in display order.
urlstring | nullnonullURL of the explorer page, joined relative to base_url (e.g. explore/; a leading slash is tolerated). When set, chart pages render an "Explore this data" button that opens this page pre-loaded with the chart's current files and time window. Absent means no cross-link.

Explore Dataset

One explorer dataset: an export stage surfaced as a named DuckDB view.

FieldAccepted typeRequiredDefaultDescription
exportstringyesnot specifiedName of the exports: stage providing this dataset's parquet files.
labelstringyesnot specifiedHuman-readable label shown in the dataset picker.
tablestringyesnot specifiedDuckDB view/table name the explorer registers (SQL identifier).

Export Stage

An export stage: runs pond export internally to produce data files that become template context.

FieldAccepted typeRequiredDefaultDescription
namestringyesnot specifiedName referenced by routes (e.g., "params", "sites")
patternstringyesnot specifiedPond glob pattern or format-provider URL pattern. Bare paths (e.g., /reduced/single_param//.series) are resolved directly as queryable pond files. URL-scheme patterns (e.g., jsonlogs:///logs/watershop/*.jsonl) are resolved through the format provider registry, allowing raw data files to be queried via DataFusion.
target_pointsintegerno1500Target data points per screen width for partition sizing. Typical value: 1000-2000. Default: 1500. Controls how parquet files are temporally partitioned per resolution. Constraints: format="uint64"; minimum=0.
timestamp_columnstringno"timestamp"Name of the timestamp column for temporal partitioning. Default: "timestamp". Override for format-provider patterns where the timestamp column has a different name (e.g., "__REALTIME_TIMESTAMP" for journald logs).

Feed

RSS feed configuration (optional section in site.yaml).

FieldAccepted typeRequiredDefaultDescription
contentstring | nullnonullWhich content stage provides pages (default: first content stage).
descriptionstring | nullnonullChannel description (default: site title).
sectionstringno"Blog"Content section to include in the feed (default: "Blog").

Report

A named, transport-independent report.

FieldAccepted typeRequiredDefaultDescription
include_pond_sizebooleannofalseInclude the pond's allocated storage size.
messagestring | nullnonullOptional reminder or explanatory text below the heading.
sectionsarray of Report Sectionyesnot specifiedOrdered data sections.
titlestringyesnot specifiedHeading shown in rendered report artifacts.
windowstringyesnot specifiedTrailing time window, such as 7d or 168h.

Report Section

A numeric series included in a report.

FieldAccepted typeRequiredDefaultDescription
capturesarray of stringno[]Exact wildcard captures selecting one file from the export pattern.
chartbooleannofalseRender a static PNG line chart.
exportstringyesnot specifiedName of an entry in exports.
hrefstringyesnot specifiedRelative or absolute link to the corresponding site page.
summaryReport Summaryno"range"Summary calculation.
titlestring | nullnonullOptional heading override. Defaults to the first capture's configured site label, then to a title-cased capture value.
unitstringyesnot specifiedDisplay unit appended to numeric values.
valuestringyesnot specifiedNumeric column to summarize and chart.

Report Summary

Numeric aggregation shown for a report section.

Accepted value: "range" | "sum".

Route

A route in the hierarchical route tree.

FieldAccepted typeRequiredDefaultDescription
annotationsstring | nullnonullOptional secondary export whose files are handed to the page as annotation data (e.g. leak/no-leak interval periods drawn as a shaded chart background). Resolved pond-wide (all files of the named export), so every page under the route shares the same annotations.
contentstring | nullnonullFor content routes: which content stage provides pages
exportstring | nullnonullFor template routes: which export stage provides data
namestringyesnot specifiedRoute name (for logging/debugging)
pagestring | nullnonullPath to markdown page (e.g., "/site/index.md")
routesarray of Routeno[]Nested child routes
slugstringyesnot specifiedURL slug -- may contain $0, $1 for template routes
typeRoute Typeyesnot specified"static" or "template"

Route Type

Route type.

Accepted value: "static" | "template" | "content".

A child item in a sidebar entry with sub-navigation.

FieldAccepted typeRequiredDefaultDescription
childrenarray of Sidebar Childno[]Nested sub-navigation items. Empty for leaf entries.
hrefstring | nullnonullDirect URL path (e.g., "/data/well-depth.html"). Optional: parent-only entries (those with children) may omit href.
labelstringyesnot specifiedDisplay label

Sidebar Entry

A sidebar entry: either a simple label or a label with sub-navigation children.

Choose one of the following:

Label with nested sub-navigation items and optional parent href

FieldAccepted typeRequiredDefaultDescription
childrenarray of Sidebar Childyesnot specified
hrefstring | nullnonull
labelstringyesnot specified
FieldAccepted typeRequiredDefaultDescription
hrefstringyesnot specified
labelstringyesnot specified

Simple label matched by page title (exact > case-insensitive > substring)

Accepted value: string.

Site Meta

Site-wide metadata.

FieldAccepted typeRequiredDefaultDescription
base_urlstringno"/"
default_rangestring | nullnonullDefault time-range button selected when a chart first loads, given as one of the chart.js duration labels such as "1M", "3M" or "24h". When absent, chart.js falls back to its adaptive default based on the data span. The value is clamped to the ranges that fit the available data.
github_urlstring | nullnonullGitHub repository URL shown as an icon in the top bar. If absent, the GitHub icon is omitted.
home_urlstring | nullnonullDestination of Home navigation links; defaults to base_url. Does not change page or asset paths.
site_urlstring | nullnonullCanonical site URL for RSS feed links (e.g., "https://casparwater.org"). Required for RSS feed generation; if absent, feed is skipped.
titlestringyesnot specified

Static Asset

Static asset to copy verbatim.

FieldAccepted typeRequiredDefaultDescription
patternstringyesnot specified

Status Grid

Config for the per-pond systemd status card grid.

FieldAccepted typeRequiredDefaultDescription
hot_windowstring | nullnonullOptional lookback window (humantime, e.g. "1d", "12h") bounding how far back the per-unit status/tail scan reads the append-only journal series. Journal versions whose newest event predates now - hot_window are pruned before the reader materializes them, so per-render memory stays bounded regardless of retained history. The bound also applies to perf_pattern enrichment. All history remains on disk and queryable; only this default status render is windowed. Unset defaults to [DEFAULT_STATUS_HOT_WINDOW] (1 day).
journal_patternstringyesnot specifiedURL pattern resolving to the journal .jsonl files written by the journal-ingest factory, e.g. "jsonlogs:///logs/journal/*.jsonl".
perf_patternstring | nullnonullOptional URL pattern (with {pond} placeholder) resolving to the per-pond perf series produced by measure-pond.sh + sql-derived-series. When set, sitegen reads the latest (timer.active, last_run.seconds_ago, timer.interval_s, run.wall_s) row per unit within hot_window and uses it for health classification. When the lookup fails for an individual unit (missing series, unparsable data, etc.) the card stays at Health::Unknown rather than failing the build. {pond} is the unit's bare pond name -- the basename with user-pond@ / user-pond-selfmon@ prefix and .service suffix stripped. Example value: "series:///derived/p-{pond}".
tail_linesintegerno10Number of MESSAGE lines to render in the tail block per card. Constraints: format="uint"; minimum=0.
unit_globsarray of stringno[]Shell-style globs (matched against the journal file basename without the .jsonl suffix) selecting which units to render. Examples: ["user-pond@.service", "user-pond-selfmon@.service"]. Empty list disables filtering (every journal file becomes a card -- usually not what you want).

Subsite

A sub-site to generate recursively from an imported pond.

FieldAccepted typeRequiredDefaultDescription
base_urlstring | nullnonullOverride the sub-site's base_url for the combined site. If omitted, the sub-site's own base_url is used.
configstringyesnot specifiedPath to the sitegen config within the foreign pond (absolute, resolved relative to the mount point via effective_root).
namestringyesnot specifiedDisplay name (used for logging and output directory fallback).
pathstringyesnot specifiedPond path to the import mount point (e.g., "/sources/noyo").