Heine reference

This is the complete current contract for Heine-authored files, command options, and template values. Start with the README or tutorial when building a site for the first time; use this page to look up exact fields, defaults, constraints, functions, and filters. The glossary defines Heine-specific vocabulary used below.

heine.toml, .page, and _directory.toml use strict schemas: unknown fields are rejected. TOML loaded from data/ or declared as page content is arbitrary structured data.

Site root and commands

A site root contains heine.toml, content/, and templates/; data/, deploy/, LICENSES/, and locales/ are optional. Without --root, Heine checks the current directory and each parent directory. It never searches child directories.

--quick does not apply to serve.

heine.toml

heine.toml is required. Its [i18n] section is required; other sections and fields use the following defaults.

Collection definitions establish relationships only; they do not write output. Every configured collection exists in every locale, including when it is empty. Page IDs are the final deterministic tie-breaker. Published orders require every member to declare published; title orders use the collection locale's ICU collation and require titles, and weight orders require numeric weights on every member.

[kit] selects at most one installed kit. Heine checks the selected directory, manifest name, optional site version requirement, the manifest's compatible Heine-version requirement, and its required self-selecting site/heine.toml before loading kit runtime resources. A kit's [extra] defaults define the complete allowed root overlay. See Kits for the installation, adapter, and ownership model.

Taxonomies turn one configured collection into locale-local generated index and term-listing pages. Their terms are literal display and route components; they are neither slugified nor inferred across locales. See taxonomies for the route and rendering model.

Atom feeds turn one configured collection into one XML document per locale. They use collection membership but order entries by published descending, then page ID. See Atom feeds for entry requirements, empty locale feeds, and template discovery links.

Search indexes turn one or more configured collections into one JSON document per locale. Their union is ordered by page ID, independently of every collection's display order. The complete document is content-hashed by default; --quick does not update it. See search indexes for the JSON and browser-boundary contract.

The complete set of accepted theme names is in Giallo's source README under “Themes”; the linked source matches Heine's bundled registry. Use those exact names; Heine reports an unknown name at its configuration location.

Search indexes

Each configured index writes one UTF-8 JSON document per configured locale:

{
  "format": 3,
  "locale": "en",
  "documents": [
    {
      "id": "blog/example/index",
      "url": "/guide/blog/example/index.html",
      "draft": false,
      "title": "Example",
      "description": null,
      "summary": "A short example.",
      "published": "2026-08-14T07:30:00Z",
      "updated": null,
      "taxonomies": { "tags": ["Rust"] },
      "sections": [
        { "fragment": null, "text": "Source-derived opening text." },
        { "fragment": "installation", "text": "Installation\n\nSource-derived section text." }
      ]
    }
  ]
}

format is the positive schema version, currently 3. id is the locale-relative page ID and url names the literal generated page file with site.base_path applied. draft is true only in a heine serve --drafts index. title, description, summary, published, and updated are their authored page facts or null. taxonomies has configured taxonomy names in deterministic lexical order, with literal locale-local terms in authored order. Documents are ordered by page ID.

sections preserves every declared .md input in content-name order as non-empty source-derived text sections. Each section has text and a fragment. fragment is null unless the section begins at a Markdown heading with a generated identifier from the page's effective table of contents. A browser can search section text and append a non-null fragment to the document URL, or search all sections as one document by joining their texts. The source text includes headings, link labels, image alternatives, code, and recognized math source. Source-authored raw HTML adds text nodes and img alt values, while markup, comments, URLs, attributes, and script, style, or template contents do not contribute. Soft and hard Markdown breaks remain line feeds; entering or leaving a structural Markdown block and an image alternative become two line feeds. Inline Markdown and inline HTML keep authored adjacency. Heine does not lower-case, tokenize, stem, truncate, or derive text from rendered HTML.

Markdown facts

Every declared Markdown input exposes page.markdown.<name>.word_count. <name> is the same simple name used by content.<name>; non-Markdown inputs do not appear in page.markdown. The count uses Unicode default word segmentation over readable source-level Markdown text. See word counts and reading time for its inclusion rules and limitations.

[reading_time] is optional. When absent, every reading_time template field is null; when present, every configured locale must have exactly one positive rate and no unconfigured locale may appear. Heine rounds nonzero estimates up to whole minutes and reports zero for zero counted words.

_directory.toml

Place _directory.toml in a configured content/<locale>/ tree. It is non-rendered, non-published, and provides directory metadata plus recursive policy.

title = "Blog"

[metadata]
required = ["title"]

[pages]
template = "post.tera"

[pages.metadata]
required = ["title", "published", "extra.author"]

Requirements accumulate from content/<locale>/_directory.toml to a page or nested descriptor. A page template overrides its inherited default; template = false explicitly disables rendering.

*.page

Each .page defines a page. Its ID is its path below its content/<locale>/ tree without .page. Without a template, it has no output path and cannot be resolved with page().

index.page has no default weight and is excluded from sibling ordering unless it has a numeric weight.

draft = true keeps an unfinished page out of an ordinary build and every relationship derived from it, including links, collections, feeds, sitemaps, and search. Use heine serve --drafts to preview it in its real site context. When a published Markdown or template reference names an excluded draft, its checked diagnostic names the draft source path and state. A local heine serve --drafts preview can include the target when it has an effective template. draft = false is a checked error because absence already means published, and _directory.toml cannot declare draft because publication state is local to one page. A draft's declared content paths remain reserved from copied assets, but their files, metadata, template, and Markdown are checked only in that preview.

published and updated must include both a calendar date and a clock time, without a UTC offset. A bare TOML date and an offset-bearing timestamp are rejected; Heine resolves the local time through site.time_zone before exposing UTC RFC 3339 text to templates. format_date() converts those timestamps back into the editorial time zone before it formats their calendar date, so a local midnight remains the authored publication day.

Sibling navigation

The preceding page fields define one page's metadata and output. The following directory-local relationship is exposed through the template values listed later in this reference.

Sibling navigation is a directory-local sequence, independent of collections. For each locale and immediate page directory, Heine includes every rendered page with a numeric weight. It sorts them by ascending weight and then by page ID, so equal weights have a stable order. A page without a numeric weight, including a non-index page with weight = false, does not participate. index.page also needs an explicit numeric weight to participate.

siblings() returns all other participating page IDs in the same order. The optional id argument selects an exact rendered page; locale= is allowed only with id=. sibling_neighbors() returns the immediate values around the current authored page as before and after: the preceding and following members of the sibling sequence. Either is null at an end. It fails when the current page does not participate in sibling ordering.

{% set neighbors = sibling_neighbors() %}
{% if neighbors.before %}
  <a href="{{ neighbors.before.url }}">Previous</a>
{% endif %}
{% if neighbors.after %}
  <a href="{{ neighbors.after.url }}">Next</a>
{% endif %}

Use a collection when a listing needs its own configured ordering; sibling navigation has one fixed directory-and-weight model.

Output filenames

Rendered pages, like copied assets, must derive portable output filename components. They cannot use empty components, ., .., Windows device names, trailing dots or spaces, or <, >, :, ", /, \, |, ?, *, or control characters. Heine rejects output paths that differ only by case, so a published tree does not depend on the deployment filesystem's case-sensitivity policy. It also rejects NFC-equivalent Unicode spellings, such as composed and decomposed forms of café. Use one NFC-normalized spelling; Heine preserves that literal spelling rather than silently rewriting it. A page with template = false has no output path and is not subject to this output rule.

Within each content tree, template tree, and locale-resource tree, filenames must likewise be distinct after NFC normalization. Heine preserves their literal spelling, but names both source paths when it finds an ambiguity.

Declared content files

Declared content is loaded but not copied as an asset. .toml files become structured TOML, .json files become structured JSON, and every other file is text. If its first line is <!-- segment: name -->, text becomes named content segments; dotted names create nested values and repeated names become ordered arrays. Markdown links and images may use asset:<locale-root-relative-id> for a checked copied asset; ordinary Markdown URLs are unchanged.

Segment markers are recognized before Markdown is parsed. In a segmented Markdown file, a line that looks like <!-- segment: name --> is therefore a marker even when it appears inside a fenced code block. Keep literal marker examples in an unsegmented input, or phrase them so they are not marker-shaped.

For example, this declared text file begins with a segment marker, so it becomes structured content rather than one text value:

<!-- segment: introduction -->
An introduction.
<!-- segment: questions.title -->
First question.
<!-- segment: questions.item -->
One.
<!-- segment: questions.item -->
Two.

For a page declaring it as main = "questions.md", templates receive page.content.main.introduction, page.content.main.questions.title, and the ordered array page.content.main.questions.item. Segmentation applies only when the first line is a marker. Otherwise the complete file remains one text value. The declared-content guide explains when normal Markdown, segments, structured data, or several inputs fit a page.

Markdown

Heine renders Markdown with pulldown-cmark. The markdown filter renders arbitrary trusted text. The markdown(content="…") function reads one named, unsegmented Markdown declaration from the current authored page. Use the function for a page's selected table of contents or margin-footnote source so its heading IDs, local note instances, and page facts agree. The following boundaries are part of the current contract:

markdown.math and markdown.highlighting add the optional math and syntax-highlighting behavior described in the heine.toml table. They do not add a general client-side JavaScript or CSS pipeline.

Renderer adapters

A renderer profile lives in the root heine.toml under [renderers.<name>]. It describes one trusted external program, its fixed arguments, a positive timeout, accepted input forms, and the expected result shape. A valid profile remains inert until authored Markdown selects it and the build includes --allow-external-renderers. Heine never discovers, installs, or version-checks that program.

The stream protocol accepts a non-empty input subset of "body" and "file". The workspace protocol also accepts "bundle". Both protocols support HTML, MathML, SVG, image, picture, and link result profiles when they declare a fixed-argument inline or block variant. HTML must be UTF-8. MathML and embedded or published SVG must be well-formed XML with math and svg document elements respectively; Heine strips XML declarations and doctypes before embedding. When a renderer fails, Heine labels its complete Markdown request and presents the program's diagnostic output separately without rewriting it. For a workspace body request, paths and line numbers in that output refer to the isolated staged input.

A workspace profile may render the same embedded result shapes from a body, declared file, or declared bundle. Heine creates one temporary input/, output/, and work/ layout per request, stages only the checked input, runs the program in work/, and accepts only its host-selected regular file at {output_file}. That file is named result.<extension>, using the checked result extension: .html, .mml, .svg, or the configured resource extension. It lets a file-oriented renderer infer its output format without adding an output-name setting to the profile. Heine expands {input_file}, {input_dir}, {output_file} and {work_dir} only when an argument is exactly that placeholder. Extra output files, missing or empty primary output, failed processes, and timeouts fail at the request. Heine removes the temporary workspace after execution when the operating system permits it. If cleanup fails, Heine retains that workspace slot, warns about its path, and retries cleanup before another request uses the slot. SVG, image, picture, and link resource requests publish one non-empty primary output as heine-renderers/sha256-<digest>.<extension>. The digest names the returned bytes, so identical results share one generated file. Heine replaces image requests with an img element using the required alt text and link requests with an a element using the required label text. Resource bytes remain outside the copied-asset namespace, but they participate in published-artifact licensing. A profile may select licensing_record; a resource request may override it with licensing_record="…". The request option is unavailable for embedded output.

An embedded SVG request may use class = "…". Heine splits that non-empty string at ASCII whitespace, normalizes separators, and rejects repeated tokens. It adds the resulting class list to the checked root svg element after reading the renderer cache, while preserving any root classes returned by the renderer. The option is unavailable for SVG resources, HTML, MathML, image, and link results. It gives site CSS a precise styling hook without adding a wrapper or an arbitrary attribute mechanism.

A picture profile has light and dark variants for every supported placement. One request runs both variants from the same checked input and emits one native picture element. Its alt is required; caption, class, width, and height use the color-scheme picture contract. The two cache keys include their appearance role. SVG picture output is XML-checked, and known light and dark dimensions must have an exact matching aspect ratio.

[renderers.katex]
protocol = "stream"
program = "katex"
timeout_seconds = 10
cache_identity = "katex-0.19.0"
inputs = ["body"]
result = "html"

[renderers.katex.inline]
arguments = ["--format", "htmlAndMathml"]

Use an inline request:

:render[katex]`body`

Or use a block request:

:::render[katex]
x^2
:::

A block request must be an ordinary top-level Markdown block. It normally uses the shown three-colon fences. When its body contains a literal ::: line, its opening fence may be longer and its otherwise empty closing fence must have the same length or longer. It cannot occur in a list, quote, or paragraph continuation.

A request may instead select a page-owned [render.<name>] file = "…" declaration when the profile accepts "file"; declared files are read as renderer input and are never published as copied assets. Stream programs read their input on standard input and write one replacement to standard output. Heine captures bounded standard-error text for a failed program and terminates the direct child when it exceeds timeout_seconds. It does not manage a renderer's descendant process tree.

Heine caches successful renderer results below .heine/cache/renderers/v1/, outside published output. The key includes the profile identity and effective fixed configuration, placement, requested output form, and the complete checked input bytes. A source bundle contributes every checked relative path and file. A profile's cache_identity is therefore the site owner's deliberate promise to update when the installed renderer or its meaningful environment changes. --refresh-renderers bypasses reads for one build and atomically replaces matching entries. Heine removes incomplete cache companions from an interrupted write, while complete entries remain disposable working state.

data/

data/ is optional and non-published. Files must be .json or .toml; their extensionless path below data/ becomes a dot-addressable template key. data/site.toml becomes data.site, while data/navigation/main.json becomes data.navigation.main. Each path component and file stem is a simple identifier. Key collisions and symbolic links are rejected. TOML calendar dates and date-times become template strings, so format_date() can format a bare YYYY-MM-DD data value. A configured locale directory such as data/de/ is reserved for locale_data while rendering German pages and never falls back to shared data.

deploy/

deploy/ is optional. Each regular file below it is copied byte-for-byte to the matching output-root path; it is neither an asset nor template input. For example, deploy/.htaccess is published as public/.htaccess, and deploy/google123.html becomes public/google123.html. Use it for host-specific configuration or external verification files, not for files a template needs to link with asset().

Deployment paths use the same UTF-8, symbolic-link, portable-filename, case-collision, Unicode-normalization, reserved-output, and output-collision rules as copied assets. A full build removes output for deleted deployment files; --quick only updates present files and can leave deleted paths stale. See the deployment-files guide for the rationale and examples.

LICENSES/ and asset sidecars

LICENSES/ is optional. Direct .txt files named for an SPDX license or exception identifier, or LicenseRef-…, are copied to <build.output_dir>/LICENSES/. An adjacent copied-asset sidecar named asset.ext.license, or one named [licensing.records.<id>] table selected by an exact [[licensing.groups]] declaration, supplies SPDX-FileCopyrightText, SPDX-License-Identifier, and optional SPDX-FileComment facts. Sidecars are not copied. Each identifier in an expression must have matching published text; malformed declarations, orphan sidecars, overlapping group members, and a group-sidecar conflict are errors. licensing.required = true requires one declaration for every copied asset and separate renderer resource that the current build publishes. Groups use literal published output_path values, without a leading slash or site.base_path. See the asset-licensing guide. The .license suffix is reserved for these sidecars and is never copied as an asset.

Each [[licensing.groups]] table has the following strict fields:

Each [licensing.records.<id>] table has the following strict fields. Its ID must start with a lowercase ASCII letter and otherwise use only lowercase ASCII letters, digits, hyphens, and underscores:

Template contract

Templates use Tera2. Heine provides only the following render-facing values; they are scoped to the locale currently being rendered unless noted otherwise.

page.dir is the locale-relative containing directory, or the empty string for a page at the locale root. page.subdirs is its sorted immediate list of source subdirectory names. They describe the source-tree location; they do not discover pages or create output.

Combine root with a counterpart's path for a relative language-switcher link, or pass an exact locale and ID to page() for its base-path-aware URL. All Heine functions check their authored inputs and fixed keyword names at the template call site. The additional keyword names accepted by t() are Fluent message arguments. Heine checks their value types while Fluent formats the selected message; a message may ignore an argument it does not use.

Template inheritance and components use Tera2's own syntax; the tutorial shows one component. Heine does not provide a configuration or plugin hook for registering site-defined Rust filters or functions. The function and filter tables below are the complete Heine additions to a template environment.

With a selected kit, ordinary template names still resolve only below root templates/. A kit original uses kit/<name>/…; a root template can name it only when the kit declares that original public. Kit templates cannot name root templates. Root templates may invoke only manifest-declared public kit components, and root components cannot occupy the selected kit's component namespace. See Kits.

asset() IDs and page() IDs are relative to the current locale tree and never begin with /. Assign a function result with {% set guide = page(id="guide") %} before reading a field such as guide.url; Tera does not support a field access directly on a function call. asset() can resolve a shared asset such as assets/logo.svg; a non-default locale can override it below its own assets/ directory. page() resolves only rendered pages.

IDs are literal source filenames, not URL fragments: do not pre-encode spaces, #, %, or non-ASCII characters. Heine percent-encodes a resolved output path exactly once when it exposes url, relative_url, or absolute_url. For non-ASCII names, use the same NFC-normalized spelling as the filename on disk; Heine preserves that literal spelling rather than normalizing lookup IDs.

highlight_css() returns the base-path-aware URL for a stylesheet that Heine generates at markdown.highlighting.stylesheet. Its content comes from the configured light and dark Giallo themes and includes the corresponding prefers-color-scheme: dark rule; it is not a copied or user-authored asset. It is available only when [markdown.highlighting] is configured.

For latest and dimensions, a relative input is resolved from page.dir; a leading / makes it locale-root-relative.