Data Model

Hwaro's template system centers on three core types: Site, Section, and Page. This page is a template-side reference for all properties and variables you can use when building templates. For how to write content and set front matter fields, see Writing.

Hierarchy

Site
├── Config (title, base_url, ...)
├── Pages[] (standalone pages)
├── Sections[]
│   ├── Pages[] (pages in section)
│   └── Subsections[]
│       ├── Pages[]
│       └── Subsections[] (recursive)
└── Taxonomies{}
    └── Terms{}
        └── Pages[]

Relationships

• A Site contains multiple Sections and standalone Pages
• A Section contains Pages and child Subsections
• Subsections can nest indefinitely
• Taxonomies group Pages by terms

Site

The root container. Configured in config.toml.

Properties

Flat Aliases

Data Directory

Hwaro allows you to store auxiliary data in the data/ directory. Files ending in .yml, .yaml, .json, or .toml are automatically loaded and exposed via site.data.

File Structure

data/
├── authors.yml
├── products.json
├── config.toml
└── users/
    ├── alice.yml
    ├── bob.yml
    └── cho.yml

Accessing Data

Data is accessed by the filename (without extension).

For example, data/products.json:

[
  {"name": "Widget", "price": 10},
  {"name": "Gadget", "price": 20}
]

Can be accessed in templates:

{% for product in site.data.products %}
  <h2>{{ product.name }}</h2>
  <p>{{ product.price }}</p>
{% endfor %}

Subdirectories

Subdirectories under data/ become nested maps. Each file becomes a child keyed by its filename (without extension), and the parent directory itself is iterable.

Given the layout above, data/users/alice.yml, data/users/bob.yml, and data/users/cho.yml are exposed as:

• site.data.users.alice, site.data.users.bob, site.data.users.cho — individual file contents
• site.data.users — a map you can iterate to list every user

{% for name, user in site.data.users %}
  <h3>{{ name }}</h3>
  <p>{{ user.bio }}</p>
{% endfor %}

Directories nest arbitrarily: data/users/admins/root.yml → site.data.users.admins.root.

Conflicts. If a directory and a file share the same stem (e.g. data/users.yml alongside data/users/), the directory wins and the file is ignored. Hwaro emits a warning during the build so the shadowed file is not silently dropped.

Remote Data Sources

site.data can also be fed from HTTP(S) endpoints, declared in config.toml. Each source is fetched once per build, before anything renders. Templates never trigger network requests, and every endpoint the build talks to is visible in one place.

For the standalone configuration guide, including cache behavior, offline error policies, timeouts, and security boundaries, see Remote Data Sources.

[[data.remote]]
key = "team"                # exposed as site.data.team
url = "https://api.example.com/team"
format = "json"             # json | toml | yaml | csv (optional, see inference below)
headers = { Authorization = "Bearer ${API_TOKEN}" }
cache = "1h"                # skip the request while the cached copy is younger than this
on_error = "fail"           # fail | warn-and-use-cache | warn-and-skip

Templates consume the result exactly like a local data file (site.data.team), so a key can move between data/team.json and a remote source without touching any template. To turn the records themselves into pages instead of feeding templates, see Content Generation.

CSV payloads parse to an array of rows, each an array of stripped string cells, the same shape load_data() produces for .csv files.

Environment variables. ${VAR} in url and headers values is replaced from the environment. A referenced variable that is not set fails the build with an error naming the variable (elsewhere in config.toml this is only a warning); write ${VAR:-default} to provide a fallback instead. The error is raised when the source is actually fetched, so commands that never fetch (hwaro deploy, hwaro new, hwaro tool ...) keep working without the variable exported.

Caching. Payloads are cached under .hwaro/remote_data/, outside data/ and every other directory hwaro serve watches, so serve rebuilds within the TTL reuse the cache instead of re-hitting the API, and cache writes never trigger a rebuild. The cache also survives hwaro build --full (only the page cache is cleared), and it is what lets an offline build succeed with on_error = "warn-and-use-cache". .hwaro/ is self-ignoring (hwaro writes .hwaro/.gitignore when creating it), so the cache never appears in git status. During a long hwaro serve session each source is fetched once and then reused in memory: an entry with a cache TTL is re-fetched on the first full rebuild after that TTL expires, and an entry without one is fetched once for the whole session rather than on every save. If a re-fetch fails while the session already holds a payload, serve warns and keeps using it, whatever on_error says, so an editor keeps working offline. hwaro build is unaffected: it is one process per build and always follows cache/on_error exactly. A changed payload invalidates cached pages the same way an edited data/ file does.

Timeouts. Each source gets 10s to connect, 30s per read, and 120s overall. The last one spans every redirect hop and the whole body, so a source that trickles bytes just inside the read timeout can't stall the build. Exceeding any of them is a fetch failure, handled by on_error like any other.

Collisions. A remote key that also exists on disk (data/team.json next to key = "team") is a config error naming both sources, since a key must have exactly one source, so site.data.team never silently depends on which one wins.

Remote sources are deliberately config-only: load_data() and shortcodes cannot take a URL. If you need more than a GET request per source (pagination, POST bodies, reshaping), fetch with a pre-build hook into data/ instead.

Site Authors

Hwaro automatically aggregates all authors defined in the authors front matter field (authors = ["id"]) into site.authors.

Defining Authors

You can enrich author data by creating a data/authors.yml (or .json, .toml) file. Keys must match the author IDs used in the page front matter.

content/my-post.md

---
title: "My Post"
authors: ["john-doe"]
---

data/authors.yml

john-doe:
  name: "John Doe"
  bio: "Creator of things."
  avatar: "/images/john.jpg"

Usage in Templates

The site.authors object contains all authors found on the site. Each author object has:

• key: The author ID (e.g., "john-doe")
• name: The author name (from data or ID fallback)
• pages: List of pages by this author (sorted by date)
• Any custom fields from data/authors.yml

{% for id, author in site.authors %}
  <div class="author">
    <img src="{{ author.avatar }}" alt="{{ author.name }}">
    <h3>{{ author.name }}</h3>
    <p>{{ author.bio }}</p>

    <h4>Recent Posts</h4>
    <ul>
    {% for p in author.pages %}
      <li><a href="{{ p.url }}">{{ p.title }}</a></li>
    {% endfor %}
    </ul>
  </div>
{% endfor %}

Example

<title>{{ site.title }}</title>
<link rel="canonical" href="{{ site.base_url }}{{ page.url }}">

Section

A directory with _index.md that groups related content.

Properties

For the current section URL in section.html, use page.url.

Flat Aliases

From Front Matter

Iterating Pages

{% for p in section.pages %}
<article>
  <h2><a href="{{ p.url }}">{{ p.title }}</a></h2>
  <time>{{ p.date }}</time>
  {% if p.description %}
  <p>{{ p.description }}</p>
  {% endif %}
</article>
{% endfor %}

Iterating Subsections

{% for sub in section.subsections %}
<div class="category">
  <a href="{{ sub.url }}">{{ sub.title }}</a>
  <span>({{ sub.pages_count }} articles)</span>
</div>
{% endfor %}

Using section_list

For simple listings, use the pre-rendered HTML:

<ul>{{ section_list | safe }}</ul>

For custom markup, iterate section.pages directly:

<ul>
{% for p in section.pages %}
  <li>
    <a href="{{ p.url }}">{{ p.title }}</a>
    {% if p.date %}<time>{{ p.date }}</time>{% endif %}
  </li>
{% endfor %}
</ul>

Page

An individual content file (.md).

Core Properties

Rendered HTML content is available as the top-level content variable.

Metadata Properties

Computed Properties

Boolean Flags

Navigation Properties

Custom Metadata

Flat Aliases

Navigation Objects

page.lower / page.higher

Navigation follows the flat reading order across the entire site, similar to mdBook or Docusaurus. Pages are ordered depth-first through the section tree: section index → section pages → subsections (recursive). Within each section, pages are sorted by the section's sort_by setting (weight, date, or title). Pages in a directory with no _index.md come after the section tree, grouped by directory and sorted like a section's pages (by date, then path). The site root index.md always comes first.

<nav class="post-nav">
  {% if page.lower %}
  <a href="{{ page.lower.url }}">← {{ page.lower.title }}</a>
  {% endif %}
  
  {% if page.higher %}
  <a href="{{ page.higher.url }}">{{ page.higher.title }} →</a>
  {% endif %}
</nav>

page.ancestors

Parent sections for breadcrumbs. An ancestor section without a title (such as a transparent year folder) uses its directory name (2022), here and in the JSON-LD BreadcrumbList:

<nav class="breadcrumbs">
  <a href="/">Home</a>
  {% for ancestor in page.ancestors %}
  / <a href="{{ ancestor.url }}">{{ ancestor.title }}</a>
  {% endfor %}
  / <span>{{ page.title }}</span>
</nav>

page.version

Only on sites with [[versions.list]] (see Versioned Docs). nil for pages outside every version directory.

page.version_links

One row per configured version, in config order.

{% for v in page.version_links %}
<a href="{{ base_url }}{{ v.url }}"{% if v.current %} aria-current="page"{% endif %}>{{ v.label }}</a>
{% endfor %}

The global versions list ({% for v in versions %}, versions.latest, versions.all) exposes every version's root URL in the current page's language.

page.translations

{% if page.translations %}
<nav class="lang-switcher">
{% for t in page.translations %}
  {% if t.is_current %}
  <span>{{ t.code | upper }}</span>
  {% else %}
  <a href="{{ t.url }}">{{ t.code | upper }}</a>
  {% endif %}
{% endfor %}
</nav>
{% endif %}

Accessing page.extra

Custom metadata from front matter:

+++
title = "Review"

[extra]
rating = 4.5
featured = true
pros = ["Fast", "Reliable"]
+++

{% if page.extra.featured %}
<span class="badge">Featured</span>
{% endif %}

<div class="rating">{{ page.extra.rating }} / 5</div>

<ul>
{% for pro in page.extra.pros %}
  <li>{{ pro }}</li>
{% endfor %}
</ul>

A top-level outputs = ["json"] in front matter is likewise an ordinary unknown key that lands in page.extra.outputs, and it overrides the [outputs] config default for that one page/section. See Output Formats.

Time Variables

<footer>&copy; {{ current_year }} {{ site.title }}</footer>

SEO Variables

Pre-rendered HTML (backward compatible):

<head>
  {{ og_all_tags | safe }}
  {{ canonical_tag | safe }}
  {{ hreflang_tags | safe }}
  {{ pagination_seo_links | safe }}
</head>

Structured data for custom meta tag markup:

Page title, description, URL, and image are available as page.title, page.description, page.url, page.image. The seo object provides computed values specific to SEO (resolved URLs, config values).

<head>
  <link rel="canonical" href="{{ seo.canonical_url }}">
  <meta property="og:title" content="{{ page.title }}">
  <meta property="og:type" content="{{ seo.og_type }}">
  <meta property="og:url" content="{{ seo.canonical_url }}">
  {% if page.description %}
  <meta property="og:description" content="{{ page.description }}">
  {% endif %}
  {% if seo.og_image %}
  <meta property="og:image" content="{{ seo.og_image }}">
  {% endif %}
  <meta name="twitter:card" content="{{ seo.twitter_card }}">
  {% if seo.twitter_site %}
  <meta name="twitter:site" content="{{ seo.twitter_site }}">
  {% endif %}
</head>

Asset Variables

Pre-rendered <link> and <script> tags for convenience. These are generated from your config.toml settings.

<head>
  {{ highlight_css | safe }}
  {{ auto_includes_css | safe }}
</head>
<body>
  ...
  {{ highlight_js | safe }}
  {{ auto_includes_js | safe }}
</body>

Table of Contents

Only available when toc = true in front matter.

Pre-rendered HTML (backward compatible):

{% if page.toc %}
<aside class="toc">
  {{ toc | safe }}
</aside>
{% endif %}

Structured data for custom TOC markup:

{% if page.toc %}
<nav class="toc">
  <ul>
  {% for h in toc_obj.headers %}
    <li>
      <a href="{{ h.permalink }}">{{ h.title }}</a>
      {% if h.children %}
      <ul>
        {% for child in h.children %}
        <li><a href="{{ child.permalink }}">{{ child.title }}</a></li>
        {% endfor %}
      </ul>
      {% endif %}
    </li>
  {% endfor %}
  </ul>
</nav>
{% endif %}

Paginator

Available in section and taxonomy term templates when pagination is enabled (paginate in section front matter, paginate_by for taxonomies). Page 1 lives at the section URL; later pages at {url}/{paginate_path}/{n}/.

A pagination_obj variant exposes the same data as previous_url, next_url, first_url, last_url, current_page, total_pages, total_items, per_page, has_previous, has_next, and html (the pre-rendered nav, also available as the flat pagination variable).

{% if paginator is defined and paginator.number_pagers > 1 %}
<nav>
  {% if paginator.previous %}<a href="{{ paginator.previous }}">Prev</a>{% endif %}
  <span>{{ paginator.current_index }} / {{ paginator.number_pagers }}</span>
  {% if paginator.next %}<a href="{{ paginator.next }}">Next</a>{% endif %}
</nav>
{% endif %}

Taxonomy Variables

Available in taxonomy templates:

For custom listings, use get_taxonomy(). See Taxonomies.

Menus

site.menus exposes the default language's named menus (config [[menus.*]] + front-matter menus/menu registrations). Inside a template, prefer get_menu(name="...") over site.menus.<name>, since it resolves against the current page's language instead, falling back to the default language:

{% for item in get_menu(name="main") %}
<a href="{{ item.href }}"{% if item.url | active_path %} aria-current="page"{% endif %}>{{ item.name }}</a>
{% endfor %}

Entry Properties

See Menus for the full config/front-matter reference, hierarchy, and per-language behavior.

Type Reference

Quick Reference

Template Checking

{# Check for nil #}
{% if page.description %}...{% endif %}

{# Check for empty array #}
{% if page.authors %}...{% endif %}

{# Check for empty string #}
{% if page.description is present %}...{% endif %}

{# Default value #}
{{ page.description | default(value=site.description) }}

See Also

• Template Syntax — Jinja2 basics
• Functions — Data retrieval functions
• Filters — Value transformation