The Configuration File

This plugin is configured via a configuration file named index-pages.ini in the configs subdirectory of the Lektor tree.

Top-Level Indexes

Each section in the config file which has a non-dotted section name and which includes a setting for the key key defines a top-level index. The index is named after the section name.

Recognized keys:

parent_path

The lektor path of the record under which the index virtual source objects will be created. This defaults to “/”.

items

A jinja-evaluated expression which specifies the query used to determine which records are to be indexed. It defaults to parent.children, where parent is the record specified by the parent_path key (see above).

key

Required. This key defines the index key(s). It is a jinja-evaluated expression which is evaluated in a context with item set to the record to be indexed. This expression should evaluate either to a single string, or, for multi-valued keys, to a sequence of strings.

template

The names of the the Jinja template used to generate each index page. Defaults to index-pages.html.

slug_format

Specifies the URL slug to be used for the index pages in this index. This is a jinja-evaluated expression evaulated in a context with this set to the index page virtual source object. The default is this.key (or, equivalently, this._id).

subindex

To declare a sub-index, this key is set to the name of the sub-index. The sub-index must be configured in its own config section (see below.)

Fields

There may be an additional section in the config file for each index named [index-name.fields] which can be used to define fields which will be made available on the index virtual source objects.

Each key in the fields config section defines a field of the same name. The value of the key is a jinja-evaluated expression which is evaluated with this set to the index virtual source object.

Please note that the config file is first and foremost parsed by inifile, which strips outer quote marks (but only if they’re the same: " or '), before jinja gets a chance to evaluate the resulting expression. This is especially important when working with constant values for your fields.

Pagination

Pagination settings applying to all indexes may be placed in the [pagination] config section. Settings particular to a specific index (and its sub-indexes) may be placed in a config section named [index-name.pagination]. (And so on: sub-index specific pagination settings go in [index-name.subindex-name.pagination].) Settings from all of these sections are merged, with those from more specific sections overriding the settings in the generic sections.

The keys recognized in this section are enabled, per_page, and url_suffix. These work the same as the like-named keys for Lektor’s built-in pagination system and project file, with the exception that the items key is not supported.

Sub-Indexes

Sub-indexes are configured in a section named [index-name.subindex-name], where subindex-name is the name of the sub-index specified in the subindex key of the parent indexes config section ([index-name]).

The only keys supported in the sub-index config section are key, template, slug_format, and (to declare a sub-sub-index) subindex. These have the same meanings as they do for a top-level index.

Annotated Example

Because an example is worth more than a few words, here’s an annotated exmple configuration file:

# let's create our first index, called 'year'
[year]
# we want to position it below the `/blog` path, already existing in our Lektor project
parent_path = /blog
# the key used to group blog posts will be the year of the pub_date field in
# our pre-existing blog item model; pub_date needs to be of type `date` or `datetime`
# for this to work
key = "{.year:04d}".format(item.pub_date)
# this is the template file to use to render our index page
template = blog-year-index.html
# and we also want a subindex where we can group our blog posts per month
subindex = month

# these are the fields belonging to our year index
[year.fields]
# first, one called `date` that will be 1st January of the year of this index group
# we will refer to this one again in the subindex below
date = this.children.first().pub_date.replace(month=1, day=1)
# and the year itself as an int, handy to use in our template file
year = this.key|int

# here is our second index; it's a subindex to the index already created above and
# is called 'month'
[year.month]
# this time we will group our blog posts (items) by month; we don't have to worry
# about mixing up the same months from different years, as we have already grouped our
# blog posts per year in this subindex's main index
key = '{.month:02d}'.format(item.pub_date)
# this subindex's pages will be rendered using a different template file
template = blog-month-index.html

# and finally, we also want some fields to be available in our subindex page template
[year.month.fields]
# the date again as the first of the month of this subindex; `this.parent` is the
# year-index page this month-index belongs to
date = this.parent.date.replace(month=this.key|int)
# the year again (as an int, like above)
year = this.parent.year
# and the month as an int
month = this.key|int

###############################################################

# here's another index, called `tags`
[tags]
# this index also groups children from our `/blog` source object
parent_path = /blog

# `key` can be multi-valued, for example if it has the `strings` type assigned
# to it in the Lektor model; in that case items may be listed on multiple # index
# pages
key = item.tags
# yet another template file
template = tag_index.html
# now, we don't want our index pages to be accessible as subpages of /blog, so
# we redefine the slug_format to assign these index pages a path below /tag.
slug_format = "tag/%s"|format(this.key)

[tags.fields]
# and in the template file we want to be able to refer to the tag as `this.tag`
tag = this.key