Steve.org.uk

Steve Kemp's Homepage

 

 

 

Chronicle : The Blog Compiler

Chronicle is a simple blog compiler, written in Perl with minimal dependencies.

A blog compiler is something which will convert a collection of input files into a static tree of HTML and RSS files.

These can then be published online giving your viewers the ability to browse a themed blog containing:

  • Archives of your prior posts.
  • Tag-based archives of your prior posts.
  • RSS Feeds.

Because the generated site is entirely static it can be served with minimal overhead, and won't cause your server load to rise if you receive thousands of visitors.

Despite being static you can still allow users to leave comments upon your posts; they will just remain "pending" until you next rebuild your blog.

Sample Output

Because the output of the software depends upon the entries you write yourself, and the theme you've chosen to use, the look and feel of your site will vary.

However my own my personal blog shows a good example of how things might look for you.

Downloading and Installing Chronicle

The chronicle application is packaged for CPAN, the perl distribution site, and can be downloaded directly from there.

Once downloaded you can unpack the release and install system-wide via:

perl Makefile.PL
make test
sudo make install

If you're a Debian GNU/Linux user you will probably prefer the Debian release:

If you'd like to try something more cutting edge please see the chronicle git repository.

Blog Format

A sample blog entry would be a text file with contents like this:

Title:  This is the title for an entry
Tags: comma, separated, tag, names
Date: 14th August 2007

<p>This is the first line of the blog entry.</p> <p>This is the last line of the blog entry.</p>

In this example the blog has been written in HTML, but you may choose to write your entries in textile or markdown formats if you prefer.

You may specify the global format by adding "--format=xx" to your chronicle command line, or by updating your chronicle configuration file:

format = [ html | markdown | textile ]

If you do not enter a title the filename of the entry will be used, minus suffix. Similarly if you do not enter a date then the last change time (ctime) of the file will be used as a default.

(You may also use Subject: instead of Title: if you prefer, that could be useful if you setup an alias to allow emails to become posts.)

NOTE: It is mandatory to separate the body and the header of the entry with at least one blank line. If you do not do this your entry will be ignored.

Building Your Blog

Assuming you have a directory containing blog-posts, perhaps "data/*.blog", you build your blog by running:

chronicle --theme=blog.steve.org.uk --input=data --pattern='*.blog' --output=output/

This will result in the creation of lots of HTML-files beneath output/.

More advanced usage can be seen by looking at the README distributed with the code, but for example you might wish to set a title/sub-title:

chronicle --title="Steve Kemp's Blog" --sub-title="Writings about cake" ..

As of the 5.x release most of the generation of output is carried out via a series of plugins, and you may list available plugins by running:

chronicle --list-plugins

Themes are stored beneath a theme-directory prefix and you can via available choices via:

chronicle --list-themes

Plugins can be excluded if you don't like their output, and similarly you can select a different theme via the use of --theme-dir and --theme.

Implementation Notes

As of the 5.x release of chronicle all blog posts are parsed and inserted into a "temporary" SQLite database. From that database the various plugins generate the output-pages.

If you leave the database alone, (./blog.db by default), then the next time you compile the site things will be even faster.

If you prefer you are welcome to delete the database between runs though, and this won't cause any problems.

Most of the pages should update automatically if you make changes, but if ever you want to force things please run "chronicle --force ..".

 

Sitemap | Contact Me © 2014 Steve Kemp