Blogging
Pagegen has built in functionality to support blogging.
Posts
Blog posts can be organized using directories anywhere in the content directory. For example.
- content/posts/<post>
- content/posts/January/<post>
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.
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
Pages maybe tagged by setting tags page headers. 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.
Shortcode tags returns a list 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:
- Short intro
- Profile picture (see for instance gravatar shortcode)
- Social media links
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.