Blogging

Pagegen has built in functionality to support blogging.

Posts

Blog posts can be organized using directories anywhere in the content directory. For example.

Typically a list of posts will be provided on the front page. This can be achieved by using the built-in shortcode list_posts or using templates. Both of the examples below will list any post(page) found in the argument posts_dir or in it's sub directories.

Note

Posts are sorted by their publish header (in page front matter), this needs to be set for meaningful post listings (if not set it defaults to the current date)

Built in shortcode list_posts

The shortcode requires a directory to find posts in and how many posts to show. Assuming posts are somewhere in the content/posts directory then the following will list 10 newest of them in the posts directory or any of its sub directories.

<sc>list_posts('posts', '10')</sc>

Listing posts in templates

Templates allow greater flexibility in presentation. After doing pagegen --init in an empty directory, the directory themes/pgsite/templates contains blog_home_page.mako and list_posts.mako showing how posts can be listed.

To use these templates simply set the page header Template: blog_home_page.mako in the page that will list the posts, e.g. content/index for the home page.

Tags and Categories

Pages maybe tagged or categorized by setting either tags or categories page headers. Tags and categories work similarly, for brevity only tags will be explained in detail. The header values are strings separated by commas.

Tags: foo, bar

In the example above the page will be tagged both foo and bar. Pagegen will create a tag directory containing an overview page listing all tags on site, and for each tag a page listing the pages that have said tag in the output directory.

site/<environment>/
├── tag
│   ├── bar.html
│   ├── foo.html
│   └── index.html

The following site.conf settings affect the tags pages, e.g. for translation purposes:

Setting Description
tag_title Page title of tag overview page, defaults to Tags
tag_url Slug of tag directory, default tag

In the example above, if tags.mako exists in the themes template directory, then it will be used to generate index.html, otherwise pages.mako will be used. Similarly bar.html and foo.html will use tag.mako if it exists.

For categories, the site.conf settings are category_title and category_url, while the templates are category.mako and categories.mako.

Shortcodes tags and categories return lists with links.

RSS feed

Pagegen supports RSS feeds. The feed itself can be configured using the following site.conf settings.

Setting Description Default
include_rss Generate rss feed if True False
max_rss_items Maximum number of items to put in feed 15
rss_title Feed title ''
rss_description Feed description ''

To include pages in the feed add header rss include: true and publish: yyyy-mm-dd so they are sorted correctly.

Authors

Authors are defined centrally in authors.conf, for example:

[tom]
name=Tom

[jerry]
name=Jerry

Only the sections are mandatory, but any other settings added here will be available in the templates. A few to consider:

Adding page header authors: tom will link the page to Tom, multiple authors may be specified authors: tom, jerry.

On generation a page listing all authors(index.html) and a page per author will be created.

site/<environment>/
├── author
│   ├── tom.html
│   ├── jerry.html
│   └── index.html

The following site.conf settings affect the author pages, e.g. for translation purposes:

Setting Description
authors_title Page title of author overview page, defaults to Authors
authors_url Slug of author directory, defaults to author

In the example above, if authors.mako exists in the themes template directory, then it will be used to generate index.html, otherwise pages.mako will be used. Similarly tom.html and jerry.html will use author.mako if it exists.

In templates the page.authors attribute will contain the author objects.

To list authors with links to their pages, the shortcode author can be used.