view release on metacpan or  search on metacpan

bin/chronicle  view on Meta::CPAN

plain-text blog-posts into a fully-featured HTML website containing
posts, tags, and archives.

All blog-posts from a given input directory are parsed into a 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 if
it is removed it will be recreated when needed.

=cut

=head1 DATABASE STRUCTURE

When C<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 associated with the posts,
if you choose to use tags in your entries.

The blog-entry table contains the following columns:

=over 8

=item mtime

The C<mtime> of the input file.

=item date

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

=item body

The body of the blog-post itself.

=item title

The title of the blog-post itself.

=back

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

=cut

=head1 EXTENDING WITH PLUGINS

The main driver, chronicle, is responsible for only a few small jobs:

=over 8

=item Finding Blog Posts.

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

B<NOTE> The pattern is applied recursively, if you wish to create sub-directories with your posts inside them for organizational purposes.

=item 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, unless expanded and reformatted
via a plugin.

=item Executing plugins

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

=back

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

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

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

=over 8

=item on_db_create

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

=item on_db_open

This is called when an existing SQLite database is opened, and we use it to set memory/sync options.

=item 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 the perfect place to handle format conversion, which is demonstrated in the following plugins:

=over 8

=item L<Chronicle::Plugin::Markdown>

=item L<Chronicle::Plugin::MultiMarkdown>

=item L<Chronicle::Plugin::Textile>

=back

Beyond format conversion this method is also good for expanding macros, or snippets of HTML.  (This is done by L<Chronicle::Plugin::YouTube> for example.)

=item on_initiate

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

=item on_generate

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

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

=back

Any plugin in the C<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 C<--exclude-plugin=RSS,Verbose>.

=cut

=head1 THEMES

There is a small collection of themes 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:

=for example begin

      $theme-dir/$theme-name

=for example end

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

Each theme will consist of a small number of template files that use
L<HTML::Template> by default but can use other templating systems depending on
the C<--template-engine> parameter. In brief, a theme is complete if it contains:

=over 8

=item C<archive.tmpl>

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

=item C<archive_index.tmpl>

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

=item C<entry.tmpl>

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

=item C<index.tmpl>

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