Sitegen shortcodes

Shortcodes expand declared site data into HTML during a build. They do not run shell commands or execute Markdown fences. Expansion uses the current page's captures, content lists, exports, and configured metadata.

Registered interfaces

ShortcodeArguments and behavior
cap0 through cap9Capture by zero-based index; {{ $0 }} is rewritten to cap0 outside literal code. Missing captures produce empty text; configured labels replace display values, not slugs.
chartOptional range; time/value chart with page export manifest, metric registry/captions, optional explorer link and annotations.
overlay_chartPump-cycle overlay using the page's files and optional explorer link; no shortcode arguments.
log_viewerLog viewer for the page's files; no shortcode arguments.
vizrenderer defaults to chart, also overlay, logs, or stacked-area; optional range for chart. Unknown renderers produce an explicit error container.
exploretable defaults to data; label defaults to that table. Configured multi-dataset exports supersede the fallback page dataset.
nav_listcollection; base (alias path) supplies the link prefix. Legacy spelling nav-list is normalized outside code.
breadcrumbCurrent route breadcrumbs; no arguments.
site_titleConfigured site title; no arguments.
base_urlConfigured project prefix; no arguments.
content_navcontent names the content stage; renders ordered, active-page-aware navigation.
figuresrc, optional caption and float (left / right); emits a figure, not a file copy.
blog_gridcontent stage and section filter; visible dated entries form cards.
pond_status_gridBuild-time configured status records and refresh label; no arguments.
sourceDocumentation-only literal inclusion: path, optional region and language, described below.

Browser behavior explains data assets and coverage boundaries; configuration supplies stages/routes and frontmatter supplies page metadata.

Daily stacked areas

A data-layout template can render an exported daily dataset directly:

{{ viz renderer="stacked-area" x="timestamp" y="views" color="section" days="30" y_title="Reported page views" order="Blog,Static content,Monitoring,Noyo,Other / unclassified" /}}

x, y, and color name the timestamp, count, and category columns; defaults are timestamp, value, and series. Input timestamps must be UTC midnight, counts nonnegative integers within JavaScript's exact integer range, and categories nonempty strings. Files must be disjoint parts of one daily dataset, not overlapping resolution tiers. Repeated day/category rows are summed.

days defaults to 30 UTC calendar days including today. y_title labels the count axis. Optional comma-separated order fixes category order and color assignments even when a named category is absent; additional categories follow alphabetically. As with other visualization renderers, use one instance per page.

The chart uses Vega-Lite stacking and step areas spanning each observed day. An absent category on a day with reported rows contributes zero; an entirely missing day remains a gap. Today is shaded and labeled partial. No collection coverage or freshness is inferred from the counts. Missing files fail the whole chart rather than display an incomplete total.

The page's route supplies its exported Parquet files. The template does not ingest observations or query a live pond, and browser date filtering is not a privacy boundary: export only the permitted public dataset.

Literal examples

In documentation mode, fenced blocks, indented blocks, and inline code bypass both variable rewriting and shortcode expansion:

{{ chart /}}
{{ $0 }}
{{ source path="/testsuite/examples/synthetic-timeseries/config.yaml" language="yaml" /}}
<script>throw new Error("literal only")</script>
$(touch /must-not-run)

Inline {{ nav-list collection="params" /}} keeps its spelling too.

{{ source path="/not-a-real-include" /}}

Source inclusion

An active directive includes escaped source, without recursive shortcode or Markdown expansion:

{{ source path="/testsuite/examples/synthetic-timeseries/run.sh" region="create-and-query" language="bash" /}}

path is an absolute input-root path, restricted by documentation.include_roots. It is not a host absolute path or a URL. region is optional; omit it for the complete file. language labels a plain code block; it does not enable syntax highlighting.

Regions use # docs:start NAME and # docs:end NAME comment lines, not line numbers. Missing files/regions, duplicate or unbalanced markers, and paths outside approved directories fail with the referring source and requested input in the diagnostic. Regions cannot nest.

This fixture deliberately contains HTML, shell text, shortcodes, and fences:

{{ chart /}}
{{ source path="/not-read" /}}
<script>throw new Error("included source is literal")</script>
$(touch /must-not-run)
```
~~~ text
& < > " '

Complete literal fixture.

The sidebar uses {{ content_nav /}} with nested sidebar entries in docs/site.yaml. Native links remain keyboard-accessible without JavaScript. Per-page contents use the same unique IDs as headings.

Relative Markdown links such as the timeseries guide resolve through the canonical source/output index, including the GitHub Pages /watertown/ prefix. Explicit frontmatter slug values override source-relative paths; duplicate output assignments fail rather than overwrite a page.

Strict builds

build OUTPUT --strict rejects missing internal targets/fragments, invalid navigation, output collisions, missing includes, partial errors, and unknown layouts. documentation.version: 1 opts in to literal preprocessing, source-relative nested slugs, _generated discovery exclusion, and lean assets. Existing sites without this block retain the legacy renderer.

The pilot layout uses local CSS and system fonts only. Data layouts can explicitly request visualization scripts and their vendor assets; ordinary manual pages do not require them. Search, highlighting, code-copy controls, and live reload are deferred.