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.

<div class="pre-lookalike">&lt;sc&gt;list_posts('posts', '10')&lt;/sc&gt;</div>


### 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](https://github.com/oliverfields/pagegen/blob/master/src/pagegen/skel/themes/pgsite/templates/blog_home_page.mako) and [list_posts.mako](https://github.com/oliverfields/pagegen/blob/master/src/pagegen/skel/themes/pgsite/templates/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.