Oliver Renderer Contract

This page is the authoritative reference for how Rotkeeper drives the native Oliver renderer — a small, freestanding CommonMark/Textile/Cooklang parsing and rendering library in Zig, and the successor to the Apex renderer. It records the stable contract between the Oliver binary and rc-oliver-adapter.sh.

Executable discovery

rc-render.sh locates Oliver in this order:

1. RK_OLIVER_BIN environment variable (explicit override).
2. oliver resolved via PATH.

If neither yields an executable file, render fails with exit 1 and prints a setup message covering installation and the environment variable.

The binary contract

Oliver is invoked once per source file, reading the file on stdin. The input language comes from input_format in bones/config/rotkeeper.yaml (markdown default, textile and cooklang alternatives), overridden to textile for any source whose extension is .textile and to cooklang for any source whose extension is .cook; the adapter and preflight pass the resulting format through on every invocation. The output profile comes from render_profile in bones/config/rotkeeper.yaml (html default, xhtml opt-in), overridden per page by a render_profile frontmatter key; only an xhtml profile appends --to xhtml, so the default invocation is byte-identical to the html-only contract:

oliver render --from markdown < file.md > body.html 2> warnings.log
oliver render --from textile < file.md > body.html 2> warnings.log
oliver render --from textile < file.textile > body.html 2> warnings.log
oliver render --from cooklang < file.md > body.html 2> warnings.log
oliver render --from cooklang < file.cook > body.html 2> warnings.log
oliver render --from markdown --to xhtml < file.md > body.xhtml 2> warnings.log

The binary is deliberately narrow: it converts Markdown, Textile, or Cooklang to a body fragment. Phase 6 complete (S1 meta, S2 wrap, S3 links, S4 plan, S5 manifest): frontmatter, template, link rewriting, output planning, manifest are Oliver-owned; Bash retains dispatch, environment, filesystem boundaries, orchestration, packaging.

Rendered Markdown surface

Oliver implements the CommonMark 0.31.2 specification; its own conformance harness scores 652/652 on the normative corpus (see the Oliver docs). That is the contract for what render produces:

• Supported: ATX and Setext headings, thematic breaks, fenced and indented code blocks (info strings become language-* classes), block quotes, tight and loose lists (ordered/unordered, nesting), code spans, emphasis and strong emphasis, inline links and autolinks (URI and email mailto:), images, raw HTML (block and inline, passed through verbatim), entity and numeric character references, reference-style links, and GFM pipe tables (header row with required delimiter row, alignment colons :--- :---: ---:, escaped \| pipes, and inline-parsed cells producing <table><thead>…<tbody>…).
• Not supported (not part of CommonMark): task lists and footnotes render as literal text. Content that needs them should stay CommonMark-safe; raw HTML is passed through verbatim as an escape hatch. The test harness asserts this boundary stays literal in contract-table.html.
• Fidelity verification: the hermetic golden (smoke-fixture-expected.html) is produced by the fixture (fake) binary and verifies the adapter pipeline — frontmatter stripping, link rewriting, escaping — not CommonMark fidelity. Renderer fidelity is asserted by the real-Oliver contract-corpus pass in the test harness (bones/scripts/tests/fixtures/oliver-contract/), which runs whenever an oliver binary is present.

Rendered Cooklang surface

Oliver implements Cooklang per the official spec and canonical corpus (60/60 on its conformance wall). That is the contract for what render produces for .cook sources and input_format: cooklang:

• Supported: @ingredient (with {braced multiword names}, quantities/units preserved as source text), #cookware, ~timers (single-word and braced; named timers render the name, unnamed the quantity/units), (preparations) shorthand, -- and [- -] comments (removed from the tree), > notes, = sections, and @./path recipe references (parsed, never resolved). Output follows Oliver's own deterministic HTML policy: <article class="recipe">, sections with <h2>, <ol class="steps"> with <li> and <br> breaks, <aside class="note">, <span class="ingredient" data-quantity data-units>, <span class="cookware">, <span class="timer">, <span class="preparation">, <span class="recipe-ref" data-ref="...">. Frontmatter is data, not content: it is never rendered.
• Not supported (degrades to literal text, per the corpus): invalid tokens; unclosed {, (, [-, or fenced blocks additionally emit a structured warning diagnostic. Recipe-reference resolution, metadata authority, and scaling are consumer territory (the .menu view and scaleRecipe live in the Oliver library, not Rotkeeper).
• Recipe metadata (title, author, servings, etc.) belongs in the leading YAML frontmatter, which Rotkeeper's adapter strips before Oliver sees it — exactly as for Markdown and Textile sources.

XHTML output profile (opt-in)

Oliver ships an explicit, deterministic, XML-compatible XHTML serialization of the same rendered document — same normalized IR, same semantics, different bytes (oliver PR #54, docs/XHTML.md upstream). Rotkeeper exposes it as an opt-in page render mode; the default (html) path is byte-identical to the pre-XHTML contract.

• Selection: render_profile in bones/config/rotkeeper.yaml (html default, xhtml opt-in; validated at environment load, anything else warns and falls back to html) arrives at the adapter as RENDER_PROFILE. A per-page render_profile key in the source frontmatter overrides the config value for that file — the per-page knob exists because raw-HTML content makes XHTML a per-page decision, not a global one.
• Flag: the adapter appends --to xhtml only when the effective profile is xhtml; an html profile appends nothing, keeping the default invocation byte-identical. preflight's smoke render passes --to xhtml too when the config selects it, so the compatibility gate covers the configured profile.
• Fragments only: the XHTML profile serializes a body fragment — no DOCTYPE, no <html>/<head>/<body> wrappers. Rotkeeper's themes own the document wrapper, so an XHTML document is a theme variant (XML declaration + <html xmlns="http://www.w3.org/1999/xhtml">), not an adapter concern. bones/templates/theme-spooky-dark-xhtml.html is the reference variant; a page opts in with template: theme-spooky-dark-xhtml.html plus render_profile: xhtml (see XHTML Output Profile, itself an XHTML page). Void elements always serialize XML-form under --to xhtml (<hr />, <br />, <img ... />); attributes stay double-quoted in the existing fixed order; escaping is the existing policy (XML predefined escapes, NUL → U+FFFD, raw Unicode preserved).
• Fail-closed on raw HTML: Markdown raw HTML (.raw_html and .html_block leaves, and Textile pre.) passes through verbatim under html but fails under xhtml with Oliver's typed error.RawHtmlNotXmlWellFormed and an actionable hint on stderr. Oliver never repairs, rewrites, or escapes raw HTML into fake XHTML, and the adapter surfaces the failure as ERROR + exit 1 for that page. A site flipping pages to XHTML must sweep its raw HTML first (the site's own docs historically contain raw HTML). The harness asserts both the fail-closed error path and XHTML well-formedness through an independent XML parser (xmllint) when a real Oliver binary is present.
• Cooklang: the forced line break is the one byte delta (<br> → <br />); recipes render through the same profile mechanism.

Frontmatter — Phase 6 S1 (Oliver-owned)

Frontmatter is parsed by Oliver via oliver meta --from <markdown|textile|cooklang> --format json < file.md (stdin → stdout JSON). Example:

oliver meta --from markdown --format json < file.md > meta.json  # {"title":"…","description":"…",…}
oliver meta --from textile --format json < file.textile > meta.json
oliver meta --from cooklang --format json < file.cook > meta.json
# Render auto-strips the same block:
oliver render --from markdown < file.md > body.html

The fields Rotkeeper reads are:

• title
• description
• author
• date
• template
• palette
• render_profile (per-page XHTML opt-in; html/xhtml, overrides render_profile in rotkeeper.yaml for that page only)

All other frontmatter keys pass through untouched. Values are HTML-escaped on template insertion. Rules retained: block must start on line 1 --- (no BOM, no leading blank line), close at next ---, ... not honored, scalar strings only (lists/maps ignored), null/empty treated as "". For the v2 template tokens (subtitle/tags/asset_meta) the adapter reads the raw source frontmatter directly with yq --front-matter extract — see Extended metadata provenance.

Template and input contract (stable)

This section is the stable contract that Phase 6 ("Rationalize the Oliver boundary") uses as its definition of truth before any renderer-adjacent responsibility moves out of Bash. It is derived from rc-oliver-adapter.sh; if the two ever disagree, the script is authoritative and this document must be updated.

Input side

• Sources are UTF-8 files with an optional leading YAML frontmatter block. The body format is Markdown by default (input_format: markdown), Textile when input_format: textile is set, Cooklang when input_format: cooklang is set, and any source whose extension is .textile or .cook renders in that format regardless of the config value. Source-file discovery covers *.md, *.textile, and *.cook; soul sidecar naming and output naming are extension-agnostic (a .textile or .cook source gets the same foo.html output and foo.soul.md sidecar as foo.md). A foo.md/foo.textile/foo.cook pair in the same directory is a source basename collision and aborts the render — only one source file may exist per page basename.
• The frontmatter block must start on the very first line (--- on line 1 — no BOM, no leading blank line) and close at the next --- line. A YAML ... document-end marker is not honored; anything after the closing --- is body content in the configured format.
• Only the seven fields above are consumed by oliver meta, as scalar strings. Lists, maps, and other keys are ignored by meta — but the v2 template tokens subtitle/tags/asset_meta are read from the raw source by the adapter's yq extraction (provenance below), and version is injected from bones/config/version.
• A .soul.md sidecar under bones/meta may override any of the six metadata fields per field (render_profile is frontmatter-only); the sidecar value wins only when it is non-empty and not null. Without a sidecar, source frontmatter applies.
• template resolution: $template$ selects ${TEMPLATE_DIR}/${template}. If the named template does not exist or escapes TEMPLATE_DIR, the batch manifest's default template (from default_template in bones/config/rotkeeper.yaml) is used. The page fails if no valid template resolves.

Template dialect

Templates are HTML files containing the following tokens:

Escaping is & < > " ' → & < > " '. $assets_root$ and $body$ are the only tokens exempt from escaping — templates must never place untrusted values there, and $body$ must never be escaped.

Conditionals: $if(name)$ … $endif$ for every metadata token (title, description, author, date, palette, version, subtitle, tags, asset_meta, navigation, warnings). When the value is empty (or null, or the key is absent) the whole block — including its interior newlines — is removed; otherwise the interior text is kept.

• Evaluation is one variable pass at a time in the order listed above, and the first $endif$ in the document closes the opener. Do not nest the same variable twice; keep conditionals single-level in practice.
• Order of operations: all $if$ blocks are resolved first, then the literal token substitution runs.
• A known token whose value is empty/absent substitutes an empty string (it is not an error); any unrecognized $word$ token passes through to the output verbatim.
• v3 generic hook (#269): a token is known if it is one of the typed metadata tokens or any key present in the --meta-json object. Present keys interpolate (strings html-escaped, null → empty, other scalars stringified, objects/arrays as compact JSON) and $if$-gate on non-empty; keys absent from meta-json stay verbatim. Injecting a new frontmatter field therefore needs no upstream change — the adapter merges it into wrap_meta and the template just references $field$.

This dialect — the typed metadata tokens (v1 five + v2 six) plus $assets_root$/$body$, escape/raw split, and the v3 generic hook for any other meta-json key — is Phase 6 S2: Oliver wrap --template <file> --meta-json <json> --assets-root <prefix> --body <file> is authoritative (direct on pin 3f05bac, wrap dialect v3, oliver #127). Example:

oliver wrap --template bones/templates/theme-spooky-dark.html \
  --meta-json meta.json --assets-root ./assets/ --body body.html > page.html
# or: oliver render --template <file> --meta-json <json> (alternative, feature-detected)

The extended tokens joined the dialect with the shared template contract v2 (rotkeeper #244, pin move 06dd640 → 8460f28, oliver #126). $version$ is not frontmatter — the adapter injects it from the canonical version source, the same single source --version and @HELP {VERSION} use. $subtitle$/$tags$/$asset_meta$ are read from the source frontmatter by the adapter with yq --front-matter extract (see provenance below); $warnings$ is reserved — no adapter feed exists yet, so it substitutes empty. Site navigation is delivered as raw HTML through a literal <site-nav></site-nav> placeholder (below), not an escaped token, because every non-literal wrap token html-escapes and a real nav is markup. The v3 generic hook (rotkeeper #269, pin move 8460f28 → 3f05bac, oliver #127): the adapter merges every other scalar frontmatter key into wrap_meta (typed keys win the merge), so templates can reference any frontmatter field as $field$ — $page_type$ on the necropolis 404 theme is the first consumer. Bash keeps TEMPLATE_DIR boundary checks; Oliver handles interpolation when wrap is present.

Extended metadata provenance (v2 + v3, implemented)

The extended tokens are live since the shared template contract v2 landed (rotkeeper #244): oliver wrap interpolates them on pins 8460f28/3f05bac (oliver #126/#127, the latter adding the v3 generic hook), and the adapter feeds them into wrap_meta:

• v3 generic merge (#269): after building the typed object, the adapter merges every other scalar frontmatter key (yq --front-matter extract -o=json '.') into wrap_meta with the typed keys winning (jq -s '.[0] * .[1]'). Any key therefore becomes an interpolatable $field$ token; values keep their JSON type and wrap renders scalars/strings/compact-JSON per the dialect. page_type on the necropolis 404 theme is the first consumer.

• oliver meta keeps emitting exactly the seven S1 fields — no map/list support was added to meta. $version$ is not frontmatter: the adapter injects it from the canonical version source (rk_load_version → bones/config/version), the same single source --version and @HELP {VERSION} use.

• The adapter (rc-oliver-adapter.sh) enriches wrap_meta with the extended scalars before invoking wrap:

  • version ← $VERSION.
  • subtitle ← frontmatter subtitle, sidecar wins (the sidecar merge is adapter-owned; the soul file is read directly because oliver meta drops it).
  • tags ← frontmatter tags list joined with , (deterministic order as authored).
  • asset_meta ← frontmatter map serialized deterministically: name, version, author, project, license joined with —, empty fields omitted, tracked never rendered (it is retrieval metadata, not display content). Example for home/content/index.md: index.md — 0.3.0.4 — Filed Systems — Rotkeeper — All Rights Reserved.
  • warnings is a reserved token with no adapter feed yet; it substitutes empty until an in-page warnings surface exists.

• Frontmatter authority splits by design: Oliver owns the seven S1 fields; yq (--front-matter extract, the same technique the harness uses) reads the extended v2 fields from the raw source because oliver meta drops lists/maps. A future oliver meta that emits every scalar key (and serializes asset_meta) would collapse the split back into Oliver.

Site navigation (<site-nav> raw-HTML slot)

$navigation$ is the config-driven site nav (topic #244). Because the recalled dialect html-escapes every non-literal token — and a nav is markup, not text — the adapter does not feed it through wrap. Instead a template declares a literal <site-nav></site-nav> placeholder and the adapter replaces it after wrap with nav rendered from bones/config/rotkeeper.yaml:

# bones/config/rotkeeper.yaml
navigation:
  label: "Primary Navigation"
  items:
    - label: "Home"
      target: "index.html"      # site-root-relative; the adapter prefixes the
      class: "txp-nav-link"     # current page's depth (./ or ../) + optional class
    - label: "Docs"
      target: "docs/index.html"
      class: "txp-nav-link"

rc-utils.sh's rk_render_navigation "$assets_root" builds <nav aria-label="…"><ul><li><a href="…">…</a></li></ul></nav> with hrefs resolved to the current page's depth (./assets/ → ./; ../assets/ → ../), then the adapter swaps <site-nav></site-nav> for it in the wrapped page (multi-line-safe via an ENVIRON AWK variable — awk -v errors on newlines). Omit the config block and the placeholder is left untouched, so unaffected themes never see it. theme-textpattern is the first consumer, replacing its hardcoded tabs. ($navigation$ is not this slot; because it is a reserved token it currently substitutes empty.)

Documentation navigation and headings

For output pages under docs/ or help/, the adapter adds a breadcrumb, a collapsible section-page list, and previous/next navigation to the literal $body$ fragment before wrap. Each navigation has a distinct <nav> landmark label. This works with every shipped theme, including the XHTML wrapper, without adding an Oliver token or changing the renderer pin.

• The current render plan is the inventory. Stale output files are never navigation targets. Breadcrumb ancestors link only when their index page exists in the plan; otherwise they appear as text.
• Docs and Help are separate sections. Each section puts its index.html first, then sorts pages by output-relative path. Previous/next links wrap around the section, so the first and last pages remain connected. A section with only one page has disabled previous/next controls instead of self-links. This is independent of the task-guide organization of the Help index.
• Labels use source titles, with non-empty soul-sidecar titles taking precedence. A page without a title uses its filename stem. Labels are HTML-escaped, path segments are URL-encoded, and targets are relative to the current page. No root-absolute URLs, CDN, or JavaScript are introduced.
• The wrapper owns the single page H1. Body H1s matching the effective title are removed, retaining their attributes on an empty span so existing fragment links survive. Other body H1s become H2s. Lower-level headings and escaped code examples remain untouched. Body-only custom templates receive a page H1 in the body instead.
• Non-documentation pages keep the normal renderer body unchanged. The Textpattern masthead uses a paragraph for site branding, leaving its article title as the only wrapper H1.

The template golden fixtures render under docs/, so they cover the shared navigation and title normalization through spooky-dark, brutal, and XHTML. The isolated documentation harness also checks every shipped template and all three layouts, escaped labels, nested paths, sidecar precedence, untitled pages, preserved anchors, and singleton navigation.

Sidecar precedence

A .soul.md sidecar next to a source file (under bones/meta) may override frontmatter fields. Sidecar wins over source frontmatter for the fields listed above. Without a sidecar, source frontmatter applies.

The adapter boundary (temporary, recorded)

rc-oliver-adapter.sh is a pure Bash batch adapter (zero Python). It currently owns:

1. Batch manifest (TSV) iteration with boundary assertions (source under content, destination under output).
2. Frontmatter extraction and sidecar merge — S1: Oliver meta --from <fmt> --format json extracts 7 scalar fields; oliver render auto-strips.
3. Template resolution — Bash retains TEMPLATE_DIR boundary; Oliver wrap --template <file> --meta-json <json> --assets-root <prefix> --body <file> interpolates.
4. Oliver invocation and stderr forwarding (including the --to xhtml flag when the effective render_profile is xhtml).
5. Internal .md/.textile/.cook → .html link rewriting — S3: Oliver render AST rewrites *.md|*.textile|*.cook → *.html.
6. Template interpolation — S2: Oliver wrap handles the v2 dialect (11 metadata tokens + html_escape + $if$/$endif$ + $assets_root$/$body$ literals).

rc-render.sh owns output planning. S4: Oliver plan --content-dir <dir> --output-dir <dir> --template-dir <dir> --meta-dir <dir> --default-template <file> --oliver-bin <bin> --root-dir <dir> --dry-run <bool> --verbose <bool> maps content → output.

rc-render.sh log_manifest owns manifest. S5: Oliver manifest --manifest <file> --add <rel> (dedup) + --verify for bones/manifest.txt.

Per the stabilization roadmap, these responsibilities are candidates for incremental movement into Oliver only after the contract above is stable. Bash keeps dispatch, environment setup, filesystem boundaries (rk_canonical_path, is_within_boundary, validate_layout_alignment, output_is_generated), orchestration, and packaging. S1+S2+S3+S4+S5 complete Phase 6; Bash retains dispatch/env/packaging.

Install paths

Oliver has no stable release yet, but upstream publishes a rolling builds release with prebuilt binaries (oliver-<os>-<arch> for linux/macos × x86_64/aarch64) plus a published sha256sums.txt. scripts/setup.sh is download-first: it fetches the platform binary, verifies it against the published checksum, and asserts oliver --version reports exactly commit <OLIVER_PIN> before installing to /usr/local/bin/oliver. Any failure falls back to building the pinned commit from source with Zig 0.16.0:

git clone https://github.com/drawmeanelephant/oliver.git /tmp/oliver
cd /tmp/oliver
git checkout --quiet <OLIVER_PIN>   # exact commit, never unpinned main
zig build                           # builds the library and CLI into zig-out/
install -m 0755 zig-out/bin/oliver /usr/local/bin/oliver

Then either put oliver on PATH or set RK_OLIVER_BIN=/path/to/oliver. CI environments (see .github/workflows/ci.yml) run scripts/setup.sh, which prefers the builds release (checksum + commit-version verified) and falls back to the Zig 0.16.0 source build when the download path is unavailable.

Smoke paths

• Availability check: bash rotkeeper.sh preflight reports whether Oliver is found, executable, and actually runnable (a live smoke render through the real CLI); it fails with one setup message otherwise. render runs the same check before rendering.
• Hermetic (always): the test harness (bash rotkeeper.sh test) builds fixture binaries and exercises frontmatter, sidecars, escaping, links, stderr separation, and manifest consistency without any Oliver dependency. The checked-in fixture at bones/scripts/tests/fixtures/oliver-smoke/ renders through a fixture binary and its body is compared against smoke-fixture-expected.html on every layout pass.
• Real binary (when present): the same harness renders real-oliver-fixture.md through the discovered executable and asserts exit 0, a well-formed HTML page, and the fixture title in the output. It runs on every layout pass. With a real binary present, the harness also renders an XHTML-profile page through --to xhtml and asserts the wrapped document is well-formed via xmllint, and asserts that a raw-HTML page selected for XHTML fails with error.RawHtmlNotXmlWellFormed. Setting RK_STRICT=1 turns the real-binary skip paths (missing oliver, missing contract corpus) into hard failures so a green run always proves the real binary was exercised — CI runs the harness with RK_STRICT=1.
• Quick local check: bash rotkeeper.sh render on a checkout with content renders everything through Oliver; failures list the page and Oliver's stderr.