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.
Uncomment
static_dir
in yourconfig.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"
(optional) Uncomment
static_flavours
in yourconfig.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"]
(optional) Uncomment
static_index_flavours
in yourconfig.py
file.static_index_flavours
is just likestatic_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.
(optional) Uncomment
static_monthnames
in yourconfig.py
file.The value (either
True
orFalse
) will determine if you want month names (such asApril
) in the static pages.Defaults to True.
For example:
py["static_monthnames"] = False
Uncomment
static_monthnumbers
in yourconfig.py
file.The value (either
True
orFalse
) will determine if you want month numbers (such as04
forApril
) in the static pages.Defaults to False.
For example:
py["static_monthnumbers"] = False
Set
base_url
in yourconfig.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 werehttp://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 instatic_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}