/ 
App-Chronicle-5.0.3
River stage zero No dependents
/ chronicle

NAME

chronicle - A static blog-compiler.

SYNOPSIS

chronicle [options]


Path Options:

 --comments       Specify the path to the optional comments directory.
 --config         Specify a configuration file to read.
 --database       Specify the path to the SQLite database to create/use.
 --input          Specify the input directory to use.
 --output         Specify the directory to write output to.
 --pattern        Specify the pattern of files to work with.
 --theme          Specify the theme to use.
 --theme-dir      Specify the path to the theme templates.
 --url-prefix     Specify the prefix to the generated blog.

Counting Options:

 --comment-days=N    The maximum age a post may allow comments.
 --entry-count=N     Number of posts to show on the index.
 --rss-count=N       Number of posts to include on the RSS index feed.

Optional Features:

 --author        Specify the author's email address
 --blog-subtitle Set the title of the blog
 --blog-title    Set the title of the blog
 --force         Always regenerate pages.

Help Options:

 --help         Show the help information for this script.
 --list-plugins List the available plugins.
 --list-themes  List the available themes.
 --manual       Read the manual for this script.
 --verbose      Show useful debugging information.
 --version      Show the version number and exit.

ABOUT

Chronicle is a blog-compiler, which will convert a directory full of plain-text blog-posts into a fully-featured HTML website containing posts, tags, and archives.

All blog-posts from the specified input directory are parsed into an SQLite database, which is then used to generate the output pages.

The SQLite database is assumed to persist, such that it will be updated if new posts are written, or previous posts are updated, however the software will cope if it is removed between runs - it will just be regenerated.

DATABASE STRUCTURE

When chronicle is first executed it will create an SQLite database if it is not already present.

The database will contain two tables, one for the posts, and one to store the tags.

The blog-entry table contains the following columns:

mtime

The mtime of the input file.

date

The date-header as self-reported in the blog-post.

body

The body of the blog-post itself.

title

The title of the blog-post itself.

If you wish to add extra tables via a local plugin you're welcome to do so.

EXTENDING WITH PLUGINS

The core of this script is responsible for only a few small jobs:

Finding Blog Posts.

By default data/*.txt are read, but you may adjust the input directory via the --input command-line flag. The pattern may be set with --pattern.

Inserting them into the SQLite database.

The header is read to look for things such as the post-date, the subject,

and the tags. The body is imported literally.

Executing plugins

Each registered plugin will be invoked in turn, allowing the various output parts to be generated.

The output is exclusively generated by the plugins bundled with the code.

For example all of the tag-pages, located beneath /tags/ in your generated site, are generated by the Chronicle::Plugin::Generate::Tags module.

The core will call the following methods if present in plugins:

on_db_create

This is called if the SQLite database does not exist, and can be used to add new columns, or tables.

on_db_open

This is called when the database is opened, and we use it to set memory/sync options. It could be used to do more.

on_insert

This method is invoked as a blog entry is read to disk before it is inserted into the database for the first time - or when the item on disk has been changed and the database entry must be refreshed.

This method is designed to handle Markdown expansion, etc.

on_initiate

This is called prior to any generation, with a reference to the configuration options and the database handle used for storage.

on_generate

This is called to generate the output pages. There is no logical difference between this method and on_initiate except that the former plugin methods are guaranteed to have been called prior to on_generate being invoked.

Again a reference to the configuration options, and the database handle is provided.

Any plugin in the Chronicle::Plugin:: namespace will be loaded when the script starts.

You might wish to disable plugins, and this can be done via command-line flags such as --exclude-plugin=RSS,Verbose.

THEMES

There are a small collection of themese bundled with the release, and it is assumed you might write your own.

Themes are located beneath a particular directory, such that the files contained in one are located at:

$theme-dir/$theme-name

These two names can be set via --theme-dir and --theme respectively.

Each theme will consist of a small number of HTML::Template files. In brief a theme is complete if it contains:

archive.tmpl

This is the file used to generate an archived month/year index.

archive_index.tmpl

This is the file used to generate the top-level /archive/ page.

entry.tmpl

This is the file used to generate each individual blog-entry.

index.tmpl

This is the file used to generate your front-page.

index.rss

This is the file used to generate your RSS feed.

tag.tmpl

This is the file used to generate the top-level /tag/XX/ page.

tag_index.tmpl

This is the file used to generate the top-level /tag/ page.

Each theme page will receive different data, as set by the appropriate generation plugin, and any global Chronicle::Plugin::Snippets plugins which have been loaded.

AUTHOR

Steve
--
http://www.steve.org.uk/

LICENSE

Copyright (c) 2014 by Steve Kemp. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The LICENSE file contains the full text of the license.