Examples

“Simple” Example: A Category Index

Let’s assume your blog posts already include a string-valued category field in their datamodel, and the blog posts live under the blog at Lektor path /blog. A category index could be generated with the following configuration in configs/index-pages.ini.

configs/index-pages.ini

[category]

# index page is rooted at /
parent_path = /

# the blog children are what is indexed
items = site.get('/blog').children

# the category field of each post is what is being indexed
key = item.category

# the index pages will be placed at URL path /category/<category>/
slug_format = 'category/{}'.format(this.key)

# this template will be rendered, once for each category to generate the index pages
template = category-index.html

[category.fields]
# Define the `category` field of an index pages to be an alias for the index key
# (in this case the category)
category = this.key

The index template, in configured above to be category-index.html, might look like:

templates/category-index.html

{% extends "layout.html" %}

{% block body %}
  <h1>Category {{ this.category }}</h1>
  <p>Posts in this category:</p>
  <ul>
    {% for post in this.children %}
      <li><a href="{{ post|url }}">{{ post.title }}</a></li>
    {% endfor %}
  </ul>
{% endblock %}

In the template for the blog parent page (at /blog) one could do something like this to link to the category index pages:

templates/blog.html

{% extends "layout.html" %}

{% block body %}
  <h1>The Blog!</h1>
  <p>Categories in this blog</p>
  <ul>
    {% for cat_idx in index_pages('category') %}
      <li><a href="{{ cat_idx|url }}">{{ cat_idx.category }}</a></li>
    {% endfor %}
  </ul>
{% endblock %}

A Hairier Example: Date Index by Year and Month

In configs/index-pages.ini:

config/index-pages.ini

[year]
parent_path = /blog
key = '{.year:04d}'.format(item.pub_date)
template = blog-year-index.html
subindex = month

[year.fields]
date = this.children.first().pub_date.replace(month=1, day=1)
year = this.key|int

[year.month]
key = '{.month:02d}'.format(item.pub_date)
template = blog-month-index.html

[year.month.fields]
# this.parent is the year-index page this month-index belongs to.
date = this.parent.date.replace(month=this.key|int)
year = this.parent.year
month = this.key|int

This will create year-index pages at URL path /blog/YYYY/ and month-indexes at /blog/YYYY/MM/.

Note that if the blog-post post slug format is properly configured — something like

models/blog.ini

[...]

[children]
slug_format = '{0.pub_date.year:04d}/{0.pub_date.month:02d}/{0._id}'.format(this)

[...]

then blog posts will be placed at /blog/YYYY/MM/post-id/ which will jibe nicely with the index URL layout described above.