Using the Blog Facilities

Overview

SiteTool has a plugin for the management of blogs. It works as follows:

• You create a blog directory
• Inside that directory you create a tag directory and a directory for each year you have blog posts for
• You then write blog posts in reStructuredText format as a .rst file with fields for Posted and Tags as that top specifying the date the post was made and the tags (or categories) it should be listed under
• You create a config file with some settings about the blog such as the title, the heading and the template the posts should use
• You run the sitetool convert sub-command to turn your .rst files into HTML pages, automatically generate indexes for each tag and each year and correctly link together the posts

Populating a blog from an existing Wordpress installation

If you have a Wordpress blog but wrote the content in reStructuredText rather than HTML you can export the posts directly to the format the Blog plugin requires, including the comments. See the Wordpress Guide for details.

A typical blog post

Say your blog directory is at /blog and you want to write a post in 2009 about databases. You’d create a 2009 sub-directory and add your databases.rst file in the correct format. It might look something like this:

All About Databases
+++++++++++++++++++

:Posted: 2009-07-30 12:16
:Tags: Databases, Coffee

This is my really interesting post about databases.

I like coffee as well as databases.

Configuring the Blog

You can specify some blog settings in the SiteTool config file. For example, this might be at /about.html in your website directory structure and contain the following content:

<table class="commandtool-config">
<tr>
    <td><tt>BLOG_DIRECTORIES</tt></td><td>Blog directory for the blog</td><td>blog/</td>
</tr>
<tr>
    <td><tt>BLOG_TITLE</tt></td><td>Blog title</td><td>Blog</td>
</tr>
<tr>
    <td><tt>BLOG_HEADING</tt></td><td>Blog heading</td><td>James Gardner's Blog</td>
</tr>
<tr>
    <td><tt>BLOG_TEMPLATE</tt></td><td>Blog template</td><td>Templates/jimmyg.dwt</td>
</tr>
</table>

When you specify the config file on the command line, SiteTool can extract the values you’ve configured.

Note

If you have specified a custom template with the correct title and heading you don’t need to also specify the BLOG_HEADING and BLOG_TEMPLATE options because if they are not specified, the default from the templates are used instead.

Updating the Blog

Every time you write or modify a post in reStructuredText format you’ll need to update the blog. You can do so with these commands:

due convert -c about.html -urCS blog
due convert -c about.html -gfrCS blog

The first looks for any files which have changed and updates them. The second forces the blog indexes to be updated.