Template Variables

When archival renders a page, it makes a handful of variables available to your liquid templates automatically — in addition to the objects you’ve defined. This page is a reference for those built-in variables.

Global variables

These variables are available in every page and template:

  • objects — every object type on your site, keyed by its name. objects.post is the list of all post objects; objects.home is a single home object. This is the most explicit way to reach any object type.
  • pluralized accessors — for convenience, each object type also gets a top-level variable. A type that holds a list is exposed under its pluralized name, and a single (root) object keeps its name. So a post type becomes posts, while a home object stays home:
{% for post in posts %}
  <a href="/{{ post.path }}">{{ post.title }}</a>
{% endfor %}
  • site_url — the site_url value from your archival.toml, as a string. Useful for building absolute URLs:
<link rel="canonical" href="{{ site_url }}/{{ post.path }}" />
  • page — the name of the page currently being rendered.

  • archival — what the social web has done with your site, and your payment account's catalog, when the build was given them. See The archival global.

These variables are also available inside partials rendered with {% render %}, which otherwise sees only the arguments passed to it (see Partials).

The archival global

archival holds what Archival knows about your site that your objects don't: the follows, likes, replies and mentions your pages have had across the fediverse, Bluesky and other sites, and your payment account's catalog. Each part answers in the shape the matching carrier call does, with its keys in snake_case, so a page can show it as plain HTML with nothing to fetch.

In a template What it holds The carrier call it matches
archival.activitypub your fediverse account and accounts, your followers, and posts[path], each with its counts, likes, boosts and replies site.activitypub
archival.atproto your Bluesky account, your followers, and posts[path], each with its counts, likes, reposts and replies site.atproto
archival.webmentions pages[path], each with its counts and its list of mentions site.webmentions
archival.interactions [path]: an object's replies and reactions from every network merged, with combined counts
archival.generated_at when the social snapshot was taken
archival.payments your payment account and its catalog. See The catalog in templates. site.payments

Posts and interactions are keyed by an object's path, and webmentions by the path of the page that was mentioned. A path nothing has reached reads as an empty answer, with counts of 0 and empty lists, so a template needs no {% if %} around it:

{% assign social = archival.interactions[post.path] %}
<p>{{ social.counts.likes }} likes, {{ social.counts.replies }} replies</p>
{% for reply in social.replies.items %}
  <blockquote>
    <a href="{{ reply.author.url }}">{{ reply.author.name | default: reply.author.handle }}</a>
    {{ reply.content | strip_html }}
  </blockquote>
{% endfor %}

In archival.interactions, each reply and reaction carries the network it came from (activitypub, atproto or webmention), and each reaction its kind (like or repost). A reply's content is HTML someone else wrote, so strip or escape it rather than output it as markup.

Lists are pages shaped { items, total, next }, as a carrier's are: total counts everything, while items holds only what the snapshot took. A page that wants all of a long list, or counts as of this minute, reads them from a carrier when it loads.

Where the values come from. A build is handed them as snapshots, which are JSON files shaped like what the carrier calls answer:

  • Social. archival build --social <file>, from archival 0.27.2, renders activitypub, atproto, webmentions, interactions and generated_at from a file described by archival_social.schema.json. Its keys are camelCase, as a carrier's response is, and templates read them in snake_case. Without one, every social value is the empty answer, which is also what archival run renders.
  • Payments. archival build --payments <file>, or a file named by the ARCHIVAL_PAYMENTS environment variable for archival run, renders payments, from archival 0.28.0. Without one, or with "account": null in the file, archival.payments reads as a site with no payment account. See Running locally for the file.

The build records what it rendered. From archival 0.28.0, a build given either snapshot writes a hash of the whole archival global to archival.toml as archival_global_hash, and rewrites that one line only when the global changes. A new follower or a changed price then shows up as a change to your repository, which a deploy can rebuild on. generated_at is left out of the hash, since every snapshot has a new one. Leave the value to the build, and pass every snapshot your site uses to every build that can write it: a build given only one reads the other as empty, and the hash would flip between them.

Because archival fills in archival, a top-level object may not be named archival. A field or child object may.

Variables on a template page

When an object type defines a template, that template is rendered once for each object of that type (see Page Templates). Inside that template, the current object is available under its definition name — for a post type, that’s {{ post }} — and each object also carries a few extra fields:

  • object_name — the type name of the object (e.g. "post"). Access it as {{ post.object_name }}.
  • order — the object’s order value, if it has one. Access it as {{ post.order }}.
  • path — the object’s path within your site, in the form <object-type>/<filename> (e.g. post/my-first-post). Access it as {{ post.path }}.
<article data-order="{{ post.order }}">
  <h1>{{ post.title }}</h1>
  <a href="/{{ post.path }}">permalink</a>
</article>

path is available on every object

Every object carries path, including objects you reach through objects or a pluralized accessor. This makes it easy to build links to objects that render their own pages:

<ul>
  {% for post in posts %}
    <li><a href="/{{ post.path }}">{{ post.title }}</a></li>
  {% endfor %}
</ul>

Because path and order are populated by archival, they are reserved — you can’t define your own object fields with those names, and archival will error if you try.

page_content (inside layouts)

One more special variable, page_content, is available inside layouts. It contains the rendered content of the page that invoked the layout. See the Layouts page for details.