Back and next

At the bottom of this post are two links: the post before it and the one after. The manual has them too, as Back and Next (#136). A page asks for them on behalf of the pages below it: its setting Back and next links on the pages below (back_next = true) is on for /manual and /blog. For posts, which a blog lists newest first, the links say Older and Newer instead.

The neighbours in a list

neighbours in crates/qed-core/src/generator.rs first takes the series: the posts below the same page in the order a Post list shows them, or the other pages in the order a Page list shows them. Then it finds the page in it:

let Some(index) = series.iter().position(|other| other.path == page.path) else {
    return Neighbours::default();
};
let before = index.checked_sub(1).and_then(|i| series.get(i));
let after = series.get(index + 1);

position gives the index of the first match, as an Option (Elixir: Enum.find_index).

The page after is easy: series.get(index + 1). Unlike series[index + 1], which stops the program when the index is past the end, get returns None for the last page.

The page before needs care. An index is a usize, a number that can't be negative. For the first page, index - 1 would be "minus one", which usize can't hold: Rust stops a debug build with an "attempt to subtract with overflow", and a release build wraps around to the largest possible number. Neither is what we want. checked_sub returns None instead, and and_then only calls get when there is a number. In Elixir, Enum.at(list, -1) would quietly return the last element, a bug that looks like a feature.

Which side

For pages, the one before goes on the left ("← Back") and the one after on the right ("Next →"). Posts come newest first, so the one after in the list is the older one, and it goes on the left:

left: after.map(|other| link(older, other)),
right: before.map(|other| link(newer, other)),

Both stay Options: the first page has no left link, the last none on the right.

Option in the template

The template takes them as they are. Askama, like Rust, can unpack an Option with if let:

{%- if let Some(link) = neighbours.left %}
<a class="flex flex-col gap-1 rounded-box p-3 …" href="{{ link.href }}">
  <span class="text-sm text-base-content/60">← {{ link.label }}</span>
  <span class="font-medium">{{ link.title }}</span>
</a>
{%- endif %}

If the template tried to use neighbours.left.title without unpacking it, the build of q.e.d. itself would fail, since askama turns templates into Rust code. A page without a neighbour can't end up with an empty link.

The words come in the site's language: German sites get "Zurück", "Weiter", "Älter" and "Neuer". The links are left out of the search index (data-pagefind-ignore), so searching for a page's title doesn't also find its neighbours.

The neighbours in a list

Which side

Option in the template

Links