Chronicle : The Blog Compiler

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

NOTE: Chronicle has been superseded by a replacement application written in golang, called ephemeris:

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.

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

If there is a particular plugin, or two, you'd like to exclude that can be achieved by adding:

chronicle --exclude-plugin=Foo,Bar

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

chronicle --list-themes

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 configuration file, but if you prefer you're welcome to specify it upon a per-post basis

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

This is written in **Markdown**.

This is [a simple link](http://example.com/).

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.

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'd like to try something more cutting edge please see the chronicle git repository.

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 ..".