| Author: | PyBlosxom Development Team |
|---|---|
| Version: | static_rendering.txt 1047 2007-06-20 18:20:49Z willhelm |
| Copyright: | This document is distributed under the MIT license. |
Contents
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 web-site.
PyBlosxom's static rendering allows for incremental building. It can scan your entries, figure out what's changed, and render only the pages that need re-rendering.
Beyond that, it's not particularly sophisticated.
These are the instructions for configuring static rendering in PyBlosxom.
Install PyBlosxom.
You can install PyBlosxom as a Python library like this:
python setup.py install
and move on to step 2.
If you can't or don't want to do that, then just untar the pyblosxom .tar.gz file into a directory.
If you're using a version of PyBlosxom prior to 1.4, when you're copying the pyblosxom.cgi and config.py files, you don't have to put them in a CGI directory--you can put them in any directory you have permissions in.
For example, I created a directory /home/joe/pyblosxom/ and put both files in there.
If you're using PyBlosxom 1.4 or later, copy bin/pyblcmd and web/config.py.
Add ``static_dir`` to 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.
Add ``static_flavours`` to your ``config.py`` file.
The value of static_flavours should be a list of strings representing all the flavours that should be rendered. This defaults to [ "html" ].
Add ``static_monthnames`` to your ``config.py`` file.
The value (either 1 or 0) will determine if you want month names (such as April) in the static pages.
Add ``static_monthnumbers`` to your ``config.py`` file.
The value (either 1 or 0) will determine if you want month numbers (such as 04 for April) in the static pages.
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://www.joe.com/~joe/, then you probably want to set your base_url like this:
py["base_url"] = "http://www.joe.com/~joe/"
Here's an example of static rendering configuration:
py["static_dir"] = "/home/joe/public_html/static/" py["static_flavours"] = ["html"] py["static_monthnames"] = 0 # i do not want month names py["static_monthnumbers"] = 1 # i do want month numbers
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").
If you're using PyBlosxom 1.4 or later, run the static renderer like this to render all pages in your blog:
% pyblcmd --config <config-file> --static
where <config-file> is replaced by the absolute full path of your config.py file. For example:
% pyblcmd --config /home/joe/blog/config.py --static
If you're using a version of PyBlosxom earlier than 1.4, then the config.py file must be in the same directory as the pyblosxom.cgi file. Run the static renderer like this:
% ./pyblosxom.cgi --static
Lots of output will appear as PyBlosxom figures out all the urls that need to be rendered and then renders them.
We have incremental rendering which will find all the entries that have changed since we rendered them and then re-render them. It does this by comparing the mtime on the entry file with the mtime on the rendered file.
If you're using PyBlosxom 1.4 or later, run the static renderer like this to render new pages in your blog:
% pyblcmd --config <config-file> --static incremental
If you're using a version of PyBlosxom earlier than 1.4, then run the static renderer like this:
% ./pyblosxom.cgi --static --incremental
Some plugins provide other URIs 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:
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"] = ["/booklist/index.html", "/index.xml"]
Static rendering is pretty simplistic. We use the tools.render_url function to render each url. Plugins that need to re-render the entry pages because something has changed (e.g. comments, pingbacks, ...), should call this function.
If you want to statically render your blog every night, you could write a shell script like this:
#!/bin/bash
export CONFIG = <path to config.py here>
export STATIC_DIR = <your static dir here>
pyblcmd --config ${CONFIG} --static
find ${STATIC_DIR} -mmin +30 -exec 'rm' '{}' ';'
That'll re-render everything, then delete any files in your static dir that are older than 30 minutes (in case you moved entries from one category to another or deleted an entry or something along those lines).
Note
A note about other files:
If your web-site requires more files than just the ones that are rendered by PyBlosxom (images, CSS, ...), then you should copy those over with your shell script as well.