Deploy Pyblosxom with Static Rendering

Summary

Static rendering made its first appearance in Pyblosxom 1.0. It fills the functionality gap for people who want to use Pyblosxom, but don’t have a web server with CGI installed, don’t have CGI access, or can’t run Pyblosxom for one of a myriad of other reasons. Static rendering allows these people to run Pyblosxom on their local machine, write blog entries, render their entire site into HTML, and then use ftp or some other file copy method to move the pages up to their static website.

Pyblosxom’s static rendering also allows for incremental building. It can scan your entries, figure out what’s changed, and render only the pages that need re-rendering.

Configuring static rendering

These are the instructions for configuring static rendering in Pyblosxom.

1. Uncomment static_dir in your config.py file.

   This is the directory we will save all the static output. The value of static_dir should be a string representing the absolute path of the output directory for static rendering.

   For example, Joe puts the output in his public_html directory of his account:

   py["static_dir"] = "/home/joe/public_html"
   

2. (optional) Uncomment static_flavours in your config.py file.

   The value of static_flavours should be a list of strings representing all the flavours that should be rendered.

   Defaults to ["html"] which only renders the html flavour.

   For example:

   py["static_flavours"] = ["html"]
   

3. (optional) Uncomment static_index_flavours in your config.py file.

   static_index_flavours is just like static_flavours except it’s the flavours of the index files: frontpage index, category indexes, date indexes, ...

   Defaults to ["html"] which only renders the html flavour.

   For example:

   py["static_index_flavours"] = ["html"]
   

   If you want your index files to also be feeds, then you should add a feed flavour to the list.

4. (optional) Uncomment static_monthnames in your config.py file.

   The value (either True or False) will determine if you want month names (such as April) in the static pages.

   Defaults to True.

   For example:

   py["static_monthnames"] = False
   

5. Uncomment static_monthnumbers in your config.py file.

   The value (either True or False) will determine if you want month numbers (such as 04 for April) in the static pages.

   Defaults to False.

   For example:

   py["static_monthnumbers"] = False
   

6. Set base_url in your config.py file to the base url your blog will have.

   For example, if your static_dir were set to /home/joe/public_html and the url for that directory were http://example.com/~joe/, then you probably want to set your base_url like this:

   py["base_url"] = "http://example.com/~joe/"
   

Here’s an example of static rendering configuration:

py["static_dir"] = "/home/joe/public_html/static/"
py["static_flavours"] = ["html"]
py["static_index_flavours"] = ["html", "atom"]
py["static_monthnames"] = False    # I do not want month names
py["static_monthnumbers"] = True   # I do want month numbers

Running static rendering

There are two ways to run static rendering. The first is to render your entire blog from scratch (see Render everything) and the second is to render only the parts of the blog that will be different because of new blog entries or updated blog entries (see Incremental rendering).

Render everything

To render all pages in your blog, cd into the directory that contains your config.py file and run:

% pyblosxom-cmd staticrender

Or from any directory run:

% pyblosxom-cmd staticrender --config </path/to/blog_dir>

where </path/to/blog_dir> is replaced by the path of the directory that contains your config.py file. For example:

% pyblosxom-cmd staticrender --config /home/joe/blog/

Or, if the location of your config.py file is in your PYTHONPATH (an environment variable) then you can run pyblosxom-cmd staticrender from any directory without giving the --config option.

Lots of output will appear as Pyblosxom figures out all the urls that need to be rendered and then renders them.

Incremental rendering

To find all the entries that have changed since you last rendered them and then re-render just those entries, do what you did in Render everything, but tack on --incremental to the end.

Incremental static rendering works by comparing the mtime of the entry file with the mtime of the rendered file.

Rendering other URLs

Some plugins provide other URLs that are part of your site, but not really part of your blog since they’re not related to entries. Examples of this include the plugininfo plugin which provides information about the plugins that you’re running. You can set the static_urls property in config.py to a list of all the urls that need to be rendered every time. This list could include:

• RSS, FOAF, OPML, Atom or any other kind of feeds
• urls for plugins that aren’t related to entries (plugininfo, pystaticfile, booklist, ...)
• urls for plugins that provide other kinds of indexes (index by tag, index by popularity, ...)

static_urls takes a list of strings where each string is a url to be rendered.

For example if I wanted to render the booklist page and the RSS feed for my main page, I would set it like this:

py["static_urls"] = [
    "/index.xml",            # blog feed
    "/pages/about.html",     # about this blog page
    "/booklist/index.html",  # list of books I've read
    ]

Things to note

• Both rendering everything and incremental rendering won’t remove outdated files.
• You probably don’t want to render an rss or Atom version of every page, so don’t include those flavours in static_flavours and instead specify the urls by hand in static_urls.
• If your website requires more files than just the ones that are rendered by Pyblosxom (images, CSS, ...), then you need to copy those files over separately—Pyblosxom won’t do it for you.

Example setup

I have all my blog files located in /home/joe/blog/.

My blog consists of blog entries and also a CSS file, a JavaScript file, and a bunch of images.

My directory layout looks like:

blog/
  |- www/
  |  |- images/
  |  |- css/
  |  \- js/
  |
  |- entries/       # all my blog entries
  |- flavourdir/    # flavours and templates
  |- plugins/       # a couple of plugins I use
  |
  |- config.py      # my config.py file
  \- compile.sh     # shell script below

I render my blog to /home/joe/public_html.

I like having my blog updated nightly—that gives me time to write entries during the day at my leisure and they all appear the next day. I do this by having a compile.sh that gets run by cron every night.

The script looks like this:

#!/bin/bash

BLOGDIR=/home/joe/blog
OUTPUTDIR=/home/joe/public_html

# incrementally render entire blog
pyblosxom-cmd staticrender --config ${BLOGDIR} --incremental

# copy static files (images, css, ...)
cp -ar ${BLOGDIR}/www/* ${OUTPUTDIR}