Examples

Taxonomies

Taxonomies organize content into groups like tags, categories, or authors.

Configuration

Define taxonomies in config.toml:

[[taxonomies]]
name = "tags"
feed = true
paginate = 10

[[taxonomies]]
name = "categories"
feed = true

[[taxonomies]]
name = "authors"
Key Type Default Description
name string — Taxonomy name (used in front matter)
feed bool false Generate RSS feed for each term
sitemap bool true Include taxonomy pages in sitemap
paginate int — Pages per pagination page

Using Taxonomies

Assign terms in front matter:

+++
title = "My Post"
tags = ["crystal", "tutorial"]
categories = ["Programming"]
authors = ["Alice"]
+++

Generated URLs

For a taxonomy named tags with term crystal:

URL Content
/tags/ List of all tags
/tags/crystal/ Pages tagged "crystal"

Templates

Taxonomy Index

templates/taxonomy.html — List of all terms:

{% extends "base.html" %}

{% block content %}
<h1>{{ taxonomy_name | capitalize }}</h1>
<ul>
{% for term in taxonomy_terms %}
  <li>
    <a href="/{{ taxonomy_name }}/{{ term.slug }}/">
      {{ term.name }} ({{ term.count }})
    </a>
  </li>
{% endfor %}
</ul>
{% endblock %}

Taxonomy Term

templates/taxonomy_term.html — Pages for a specific term:

{% extends "base.html" %}

{% block content %}
<h1>{{ taxonomy_name }}: {{ taxonomy_term }}</h1>
<ul>
{% for p in taxonomy_pages %}
  <li>
    <a href="{{ p.url }}">{{ p.title }}</a>
    <time>{{ p.date }}</time>
  </li>
{% endfor %}
</ul>
{% endblock %}

Template Variables

In taxonomy.html

Variable Type Description
taxonomy_name String Taxonomy name ("tags")
taxonomy_terms Array All terms (in taxonomy.html)

In taxonomy_term.html

Variable Type Description
taxonomy_name String Taxonomy name
taxonomy_term String Current term name
taxonomy_pages Array<Page> Pages for term

Term Object

Property Type Description
name String Term name
slug String URL-safe name
count Int Number of pages

get_taxonomy() Function

Access taxonomy data anywhere:

{% set tags = get_taxonomy(kind="tags") %}
{% if tags %}
<div class="tag-cloud">
{% for term in tags.items %}
  <a href="/tags/{{ term.slug }}/">{{ term.name }}</a>
{% endfor %}
</div>
{% endif %}

get_taxonomy_url() Function

Generate taxonomy term URL:

<a href="{{ get_taxonomy_url(kind='tags', term='crystal') }}">
  Crystal articles
</a>

Common Patterns

Tag Cloud

{% set tags = get_taxonomy(kind="tags") %}
<div class="tags">
{% for term in tags.items %}
  <a href="/tags/{{ term.slug }}/" 
     class="tag count-{{ term.count }}">
    {{ term.name }}
  </a>
{% endfor %}
</div>

Display Page Tags

{% if page.tags %}
<div class="post-tags">
{% for tag in page.tags %}
  <a href="/tags/{{ tag | slugify }}/">{{ tag }}</a>
{% endfor %}
</div>
{% endif %}

Category Navigation

{% set categories = get_taxonomy(kind="categories") %}
<nav class="categories">
{% for cat in categories.items %}
  <a href="/categories/{{ cat.slug }}/">
    {{ cat.name }} ({{ cat.count }})
  </a>
{% endfor %}
</nav>

See Also