Templates

Lists of pages

A list repeats its contents once for each page in a folder. It is how you make an index, a journal, a sidebar or a row of related pages.

A list repeats everything between {{ each:… }} and {{ /each }} once for each page in a folder. Whatever sits after {{ else }} shows instead when there are none:

<ul class="col gap:d4">
  {{ each:journal:newest:10 }}
  <li>
    <a href="{{ item.url }}" class="font:h5:semibold">{{ item.title }}</a>
    <time datetime="{{ item.date-iso }}">{{ item.date:short }}</time>
  </li>
  {{ else }}
  <li>Nothing here yet.</li>
  {{ /each }}
</ul>

After each: comes which pages to list, then any sorts, limits and filters, in any order.

Which pages

WriteLists
each:journalThe pages directly inside content/journal/. Use a path for deeper folders, like each:work/clients
each:childrenThe pages directly inside the page being rendered
each:siblingsThe other pages in the same folder as this one, leaving this page out
each:itemInside another list: the pages inside each item of the outer list
each:tagsThis page's tags. See Tags and tag pages
each:item.tagsInside another list: the tags of each item
each:taggedOn a tag page: the pages with that tag
each:all-tagsEvery tag, with how many pages use it

A folder list only goes one level down: each:journal shows /journal/spring-menu/ but not pages inside it. Drafts are left out of the built site's lists. In the editor they're listed, so a new post doesn't vanish while you write it. A folder that doesn't exist stops the build, since it is almost always a typo. children and siblings make templates that work wherever a page sits, which is what a section index or a “more in this section” row wants.

Sorting, limiting and filtering

WriteDoes
newestLatest date first. The default for pages
oldestEarliest date first
a-z, z-aBy title. a-z is the default for tags
orderThe order set by dragging pages in the site view, then by title
mostFor tags: the most used first
A number, like 3Shows that many at most
skip-1Leaves out the first one (or the first n), after sorting
10:pagedShows 10 per page and makes /journal/page/2/ and on. See Pages of a list
tagged-designOnly pages tagged Design
has-coverOnly pages whose cover is filled in
no-coverOnly pages whose cover is empty
kind=essayOnly pages whose kind is essay
kind!=essayOnly pages whose kind isn't essay

Filters read the same names as item. references: a page's fields, or settings like description. Comparisons ignore capitals and spaces at the ends, so kind=essay matches “Essay”. A value with spaces goes in quotes: kind="case study". Filters stack, so {{ each:work:has-cover:kind=case-study:6 }} shows up to six case studies that have a cover.

Pages with the same date fall back to their titles. Pages with no order go after the ones that have one. Skip and limit work together, which makes a lead story and the rest easy:

{{ each:journal:newest:1 }}
  <a href="{{ item.url }}" class="font:h2:bold">{{ item.title }}</a>
{{ /each }}
{{ each:journal:newest:skip-1:6 }}
  <a href="{{ item.url }}">{{ item.title }}</a>
{{ /each }}

Anything else after each: stops with “… isn't something a list understands.” and a list of what is allowed.

When a list is empty

{{ else }} goes inside the list, before {{ /each }}. What follows it shows once, only when the list has nothing to show, after its filters. It is part of the page, not of the list, so item. references don't work there.

Counts

{{ count:… }} takes the same folder and filters as a list and shows how many pages it would list:

<p>{{ count:journal }} posts, {{ count:journal:tagged-design }} about design.</p>

Skip is taken off the count; a limit and paged aren't used.

Inside a list

References that start with item. read from the page being repeated:

ReferenceShows
{{ item.url }}The page's address, like /journal/spring-menu/
{{ item.title }}Its title, or its label when the title is empty
{{ item.label }}Its title without a “ — Site name” tail, or the name made from its folder, like “Spring menu”
{{ item.description }}Its description
{{ item.date }}Its date, written out in the site's locale, like “April 2, 2026”
{{ item.date-iso }}Its date as 2026-04-02, for datetime attributes
{{ item.tags }}Its tags, separated by commas
{{ item.count }}In a list of tags: how many pages use the tag
{{ item.cover }}Any of its fields by name: text, rich text, an image's address or a colour's value

A reference can take a format after a colon. Dates take long (the default), short, numeric, month, year or iso; text takes words-25 or chars-140, which shorten it and add “…”:

<time datetime="{{ item.date-iso }}">{{ item.date:short }}</time>
<p>{{ item.description:words-20 }}</p>

An image shown with <img src="{{ item.cover }}"> brings its alt text along, unless you write an alt yourself. Use {{ if:item.cover }} to show part of each item only when that page has something in the field. See Conditions.

Lists inside lists

Any list can sit inside another, three deep at most. each:item lists the pages inside each outer item, which is enough for a documentation sidebar, a menu with sections, or a magazine's issues and their articles:

{{ each:docs:order }}
  <h3 class="font:small:semibold">{{ item.title }}</h3>
  <ul>
    {{ each:item:order }}
    <li><a href="{{ item.url }}">{{ item.title }}</a></li>
    {{ /each }}
  </ul>
{{ /each }}

A list of tags inside a list of posts gives each post its own tags:

{{ each:journal:6 }}
  <a href="{{ item.url }}">{{ item.title }}</a>
  {{ each:item.tags }}<a href="{{ item.url }}" class="font:small">{{ item.title }}</a>{{ /each }}
{{ /each }}

Inside the inner list, item. means the inner page or tag. The outer one can't be reached from there, so put anything you need from it before the inner list starts.

What lists can't do

  • Hold fields. A list shows other pages, so it has nothing of its own to edit. Use item. references, or a repeater for items that belong to this page.
  • Go inside a tag or a <title>. Put them between elements.
  • Show pages that aren't directly inside the folder. Make a folder for each group you want to list, or use tags.
  • Split into pages when they're inside another list. Only the outermost list can be paged, and only one per page.