Data Model

Hwaro's template system centers on three core types: Site, Section, and Page. Understanding their hierarchy is essential for building templates.

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

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 %}

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>

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

<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:

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

Time Variables

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

SEO Variables

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

Asset Variables

<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:

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

Taxonomy Variables

Available in taxonomy templates:

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) }}

Example Templates

page.html

{% extends "base.html" %}

{% block content %}
<article>
  <h1>{{ page.title }}</h1>
  
  <div class="meta">
    <time>{{ page.date }}</time>
    {% if page.authors %}
    <span>by {{ page.authors | join(", ") }}</span>
    {% endif %}
    <span>{{ page.reading_time }} min read</span>
  </div>
  
  {% if page.toc %}
  <nav class="toc">{{ toc | safe }}</nav>
  {% endif %}
  
  <div class="content">
    {{ content | safe }}
  </div>
  
  {% if page.lower or page.higher %}
  <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>
  {% endif %}
</article>
{% endblock %}

section.html

{% extends "base.html" %}

{% block content %}
<section>
  <h1>{{ section.title }}</h1>
  {% if section.description %}
  <p class="lead">{{ section.description }}</p>
  {% endif %}
  
  {{ content | safe }}
  
  <h2>Articles ({{ section.pages_count }})</h2>
  <ul class="article-list">
  {% for p in section.pages %}
    <li>
      <a href="{{ p.url }}">{{ p.title }}</a>
      {% if p.date %}<time>{{ p.date }}</time>{% endif %}
    </li>
  {% endfor %}
  </ul>
  
  {% if section.subsections %}
  <h2>Categories</h2>
  <ul>
  {% for sub in section.subsections %}
    <li>
      <a href="{{ sub.url }}">{{ sub.title }}</a>
      ({{ sub.pages_count }})
    </li>
  {% endfor %}
  </ul>
  {% endif %}
  
  {{ pagination | safe }}
</section>
{% endblock %}

See Also

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