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
| Write | Lists |
|---|---|
each:journal | The pages directly inside content/journal/. Use a path for deeper folders, like each:work/clients |
each:children | The pages directly inside the page being rendered |
each:siblings | The other pages in the same folder as this one, leaving this page out |
each:item | Inside another list: the pages inside each item of the outer list |
each:tags | This page's tags. See Tags and tag pages |
each:item.tags | Inside another list: the tags of each item |
each:tagged | On a tag page: the pages with that tag |
each:all-tags | Every 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
| Write | Does |
|---|---|
newest | Latest date first. The default for pages |
oldest | Earliest date first |
a-z, z-a | By title. a-z is the default for tags |
order | The order set by dragging pages in the site view, then by title |
most | For tags: the most used first |
A number, like 3 | Shows that many at most |
skip-1 | Leaves out the first one (or the first n), after sorting |
10:paged | Shows 10 per page and makes /journal/page/2/ and on. See Pages of a list |
tagged-design | Only pages tagged Design |
has-cover | Only pages whose cover is filled in |
no-cover | Only pages whose cover is empty |
kind=essay | Only pages whose kind is essay |
kind!=essay | Only 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:
| Reference | Shows |
|---|---|
{{ 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.