Recently I've started a series of articles about solving protohackers challenges in Rust. It's an ongoing series available in this blog here. For that series I wanted to group the articles together in a meaningful way.

# Using Taxonomies

Now Zola, the fantastic static site generator written in Rust that I use for this blog, supports taxonomies out of the box. Taxonomies are a way to group content together by user-defined categories.

In this website I've implemented the tags and series taxonomies.

Taxonomies can be defined in the Zola configuration file config.toml.

taxonomies = [
    {name = "tags", paginate_by = 5, feed=true},
    {name = "series", paginate_by = 5, feed=true},
]

For each taxonomy Zola will try (if not disabled) to render one page listing all the terms defined for a taxonomy and one page for each term in the taxonomy, listing all the content associated with that term.

For example this blog post has two tags zola and blogging, and if a reader wants to know all stuff that I wrote about Zola, all the articles are grouped here.

Applying tags is super easy, I just have to specify the taxonomy tags in the content file:

+++
title = "Handling series of articles with Zola"

[taxonomies]
tags=["zola","blogging"]

+++

and the content will be automatically associated to those tags.

For rendering the taxonomy pages Zola looks up this files in the templates directory:

• $TAXONOMY_NAME/single.html : renders the single term of the taxonomy
• $TAXONOMY_NAME/list.html: renders the list of terms in the taxonomy

and those pages will be available at:

• $BASE_URL/$NAME/ (taxonomy) terms list
• $BASE_URL/$NAME/$SLUG (taxonomy entry) single term

In those templates Zola will bind for each term of the taxonomy the metadata TaxonomyTerm containing only this fields:

name: String;
slug: String;
path: String;
permalink: String;
pages: Array<Page>;

For the tag taxonomy this worked just fine and it was enough. I implemented the list.html of tags by listing all tags available, where each tag links to it's single.html page via permalink field. While in the single.html I've listed all the content associated to the single term via pages field. This is a standard way of rendering taxonomies with Zola.

For the series taxonomy I was looking for an enriched presentation, where at least I wanted to have a short description for the single series. But the only available fields related to the single term are it's name or the slug.

I'm an avid reader of fasterthanlime articles, and I like how the series are organized there. So i tried to replicate that structure in Zola.

# Enriching Taxonomies

Using the taxonomies API it's not possible to associate extra data when defining a taxonomy.

When looking for a way to achieve this, I stumbled upon this page in the Zola discourse forum.

Following the suggestion on the link above, I did define a bunch of extra fields in config.toml for the series taxonomy, that i can use when rendering single.html and list.html templates.

For example for the protohackers series I ended up adding something like this in the config.toml:

[extra.taxonomies.series.protohackers-rust]
title = "Protohackers in Rust"
date = "2023-01-16"
status = "ongoing"
description = "description"

and now in the templates, I can lookup for this extra metadata using term.slug as key

{%set extra = config.extra.taxonomies["series"][term.slug] %}

# Conclusion

Even though it's not perfect yet and nowhere near to the fasterthanlime structure, I'm pretty happy about the results. I was able to add more information, like a short description or a status (ongoing, complete) when displaying series pages.

I've some idea on how to improve this, for example I would like to auto-generate a Toc for a single series or at least provide some automatic link to the prev or next between articles.

Comments and suggestions are always welcome. Please feel free to send an email or comment on @wolf4ood@hachyderm.io.

Thank you for reading.