README.md

Lektor Atom Plugin

Builds one or more Atom XML feeds for your Lektor-based site.

Inspired by the atom-feed-support plugin Armin Ronacher wrote for the Lektor official blog.

Installation

Add lektor-atom to your project from command line:

lektor plugins add lektor-atom

See the Lektor documentation for more instructions on installing plugins.

Configuration

Here is a basic configuration:

[feed]
name = My Site's Blog
source_path = /blog
url_path = /feed.xml

For each feed you want to publish, add a section to configs/atom.ini. For example, a blog with a feed of all recent posts, and a feed of recent posts about coffee:

[blog]
name = My Blog
source_path = /
url_path = /feed.xml
items = site.query('/').filter(F.type == 'post')
item_model = blog-post

[coffee]
name = My Blog: Articles About Coffee
source_path = /
url_path = /category/coffee/feed.xml
items = site.query('/blog').filter(F.categories.contains('coffee'))
item_model = blog-post

The section names, like blog and coffee, are just used as internal identifiers.

Options

Option	Default	Description
source_path	/	Where in the content directory to find items' parent source
name	config section name	Feed name
filename	feed.xml	Name of generated Atom feed file
url_path	source_path + filename	Feed's URL on your site
blog_author_field	author	Name of source's author field
blog_summary_field	summary	Name of source's summary field
items	source_path's children	A query expression: e.g. site.query('/').filter(F.type == 'post')
limit	50	How many recent items to include
item_title_field	title	Name of items' title field
item_body_field	body	Name of items' content body field
item_author_field	author	Name of items' author field
item_date_field	pub_date	Name of items' publication date field
item_model	None	Filters items on name of items' model

Customizing the plugin for your models

Use the field options to tell lektor-atom how to read your items. For example, if your site's model is:

[model]
name = Blog

[fields.writer]
type = string

[fields.short_description]
type = string

Then add to atom.ini:

[main]
blog_author_field = writer
blog_summary_field = short_description

See tests/demo-project/configs/atom.ini for a complete example.

Filtering items

By default, lektor-atom gets the source at source_path and includes all its children in the feed. If you set item_model, lektor-atom includes only the children with that data model.

Set items to any query expression to override the default. If items_model is also specified, lektor-atom applies it as a filter to items.

Use In Templates

You can link to a specific feed in your template. If your atom.ini contains a feed like this:

[main]
source_path = /blog

Link to the feed in a template like this:

{{ '/blog@atom/main'|url }}