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.

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; block boundaries become two line feeds. Heine does not lower-case, tokenize, stem, truncate, or derive text from rendered HTML.

_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.

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 deliberately 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.

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.

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 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 such declaration for every copied asset. 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:

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 deliberately 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.

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 or relative_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.