The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Blio-2.007
River stage zero No dependents
++
/ blio.pl

NAME

blio.pl - Blio - domm's blogging "engine"

VERSION

version 2.007

SYNOPSIS

  ~/your_blog$ blio.pl --source_dir src --output_dir htdocs --template_dir templates

DESCRIPTION

Blio is a very simple blogging "engine". I call it an '"engine"' because Blio is basically a slightly enhanced and streamlined (for my use cases, at least) ttree, or yet another pre-clone of jekyll.

In other words, it takes a bunch of plain text files containing some simple headers and some content, runs them through some templates, and writes out some html files for static serving. Blio also does some other things (most notably image handling, powered by Imager).

Directory Layout

Blio needs three directories: src, out and templates.

templates contains the Template::Toolkit templates used to render the HTML, src contains all your raw content and out containes the rendered HTML content ready for serving by your favourite web server.

But there a few formal restrictions you need to observer so Blio can work:

  • Each node has to be a plain text file. It should have an all-lowercase filename. It must have an all-ascii filename. It must end in '.txt'.

  • If a node should contain sub-nodes, those have to be stored in a directory having exactly the same name as the node, but without the '.txt'.

  • If you want to link exactly one image to a node, the image has to have exactly the same name as the node, but with '.txt' replaced with a proper extension.

  • If you want to link one or more images to a node, you must put them in a directory at the same level as the node. This directory must have the same name as the node, but with '.txt' replaced by '_images'

Example

  |-- out
  |-- templates
  `-- src
      |-- iceland
      |   |-- geysir.txt
      |   |-- geysir_images
      |   |   |-- geysir_1.jpg
      |   |   `-- geysir_2.jpg
      |   |-- gullfoss.txt
      |   |-- gullfoss.jpg
      |   `-- no_image.txt
      `-- iceland.txt

Node Format

Each Node is a simple plain-text UTF8 encoded file consisting of an HTTP-like header, a blank line and the content.

Header Fields

title

The title of this blog post. Required

date

The publication date of this post. Has to be parsable by DateTime::Format::ISO8601. If this field is not set in the file, the mtime of the file will be used.

language

The language of this post. See CONFIGURATION.

converter

The converter to use. See CONFIGURATION.

feed

If set to a true value, an RSS feed will be generated containing the children of this node.

author

The name of the author of this post

tags

A comma seperated list of tags. See also the Global Config tags

paged_list

Set to a value > 0 to have the children of this node paged.

inline_images

Enable inline images

thumbnail

Thumbnail size

Content

The content can be generated using the common formatting languages supported by Markup::Unified, or HTML

Example

    # file: iceland/geysir.txt
    title: Geysir
    converter: textile
    thumbnail: 400

    Lots of water

    h4. Food
    
    There's a small tourist info where you can get soup.

INSTALLATION

Blio runs on Perl application, and thus requires a rencent Perl (>= 5.10). It also reuses a lot of code from CPAN.

From CPAN

The easiest way to install the current stable version of Blio is via CPAN and cpanminus

  ~$ cpanm Blio
  Fetching http://www.cpan.org/authors/id/D/DO/DOMM/Blio-2.002.tar.gz ... OK
  Configuring Blio-2.002 ... OK
  ... # installing dependencies
  Building and testing Blio-2.002 ... OK
  Successfully installed Blio-2.002

If you don't have cpanminus installed yet, install it right now:

  ~$ curl -L http://cpanmin.us | perl - --sudo App::cpanminus

From a tarball or git checkout

To install Blio from a tarball or a git checkout, you will need Dist::Zilla and some Dist::Zilla-plugins

  ~/perl/Blio$ cpanm Dist::Zilla
  ~/perl/Blio$ dzil authordeps | cpanm

Now you can build a Blio distributrion

  ~/perl/Blio$ dzil build

And finally you can install Blio via dzil:

  ~/perl/Blio$ dzil install

Or change into the build directory (Blio-$VERSION) and do the old install dance:

  ~/perl/Blio/Blio-2.002$ perl Build.PL
  ~/perl/Blio/Blio-2.002$ ./Build
  ~/perl/Blio/Blio-2.002$ ./Build test
  ~/perl/Blio/Blio-2.002$ ./Build install  # might require sudo

CONFIGURATION

Blio can be configured via a combination of command line options and a config file.

See MooseX::Getopt and MooseX::SimpleConfig for the implementation details.

Global Config

Global Config can be specified via command line option or the global config file.

configfile

Path to the configfile. Default 'blio.ini'. The configfile has to be parsable by MooseX::SimpleConfig.

source_dir

The directory containing the plain text source files. Here is where you generate and edit content. Default 'src'.

output_dir

The directory where the rendered HTML files are stored. This directory should be the document root of your webserver. Default 'out'.

template_dir

The directory containing the templates used to render your content. Default 'template'.

Please note that some very simple (and very ugly) default templates are provided by Blio. They come in the share/templates directory of the distribution and are installed along the module via File::ShareDir.

name

The name of your blog.

site_url

The URL of your blog (needed to generate a proper RSS feed)

site_author

Your name (needed to generate a proper RSS feed)

tags

Set to a true value if you want to use tags in your Blog. If you do, all tags will be collected and added to a vitual top node called 'tags.html'.

schedule

Set to a true value if you want to use the scheduling feature. If active, all node with a date in the future will not be rendered.

force

Force a complete regeneration of the site. Currently, this mostly means that all images will be again converted to thumbnails.

quiet

Do not producde regular output

Per-Node config

Per-Node config can be specified per node, or falls back to a global value specified via command line option or in the config file.

language

The default language of your content. You can set other languages per node. Default "en".

converter

The default text2html converter. You can choose other converters per node. Currently valid converters are: html, textile, markdown, bbcode. If you choose html, the content is not converted at all (because we assume it's already HTML). All other converters are handled via Markup::Unified.

thumbnail

The width (in pixel) of thumbnails that are generated by Blio / Imager. Default "300".

USAGE

DIRECTORY LAYOUT

NODE SYNTAX

TEMPLATES

Methods available in templates

$blio->..

$node->..

ARTICLES & PRESENTATIONS

2013.05.03

Talk at Linuxwochen 2013 Wien (in german)

2013.03.28

Building a static blog using Blio and Github

2013.01.20

Blio updates

2012.09.11

Some new Blio features

2012.08.09

Blio - my blogging "engine"

AUTHOR

Thomas Klausner <domm@plix.at>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 - 2022 by Thomas Klausner.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.