Plox - A simple Perl blogging application.

0. Contents

1. Overview
2. Requirements
3. Installation
4. Usage
5. License

1. Overview

Plox is a simple Perl blogging application, heavily inspired by Blosxom,
but written from scratch. Blog entries are stored in the file system, no
database is required to run Plox. To create, edit or delete an entry all
you have to do is create, edit or delete a plain text file.

The page style is completely customizable, Template Toolkit is used as
template processing system. Basic example templates are included in the
Plox distribution.


* Blog entries (stories) are plain text files, folders act as
  categories, no database is required.
* Template Toolkit is used as template system.
* Use flavours to display the content in any format you want, eg. HTML,
  XHTML or as Atom feed.
* FastCGI version is available, offering much better performance than
  the CGI version.
* Plox can easily be extended by plugins.
* Display stories by day, by month or by year, or by category (or
  combine these filter criteria).
* No comment spam, since comments are not supported. (Yes, it's a
  feature! ☺)
* Plox is free and open source software, licensed under the GPL 3..

Most of the functionality of Plox is provided by plugins, with the Plox
core plugin doing most of the work. Additional plugins can by used to
add or modify the data gathered by the core plugin, making it easy to
extend Plox with every feature you need. The following plugins are
currently included in the Plox distribution:

* Atom        - provides some data required for the Atom feed
* BetterTitle - generates a title for the requested page
* Gallery     - generate image galleries (experimental!)
* MoreEntries - provides a next/previous page functionality
* NotFound    - send 404 error pages instead of empty pages
* Paragraphs  - automatically insert <p> tags in the stories
* ProcessTime - measures the time it takes to generate a page
* SeyMore     - show only the first part of a story on index pages
* Today       - provides some date related information
* XhtmlMime   - send XHTML content type if the client prefers it

Some useful links:

* API and plugin documentation: <http://goeb.gitlab.io/plox/api/>
* Git repository at Gitlab:     <https://gitlab.com/goeb/Plox>
* Issue tracker at Gitlab:      <https://gitlab.com/goeb/Plox/issues/>

You can download Plox using the Download links on the repository pages,
or use Git to clone the repository. See the repository overview for

2. Requirements

The minimum requirements are:

* Un*x like operating system, eg. Linux, *BSD - Windows is not supported
  at the moment
* Perl
* Template Toolkit (Template module)
* CGI or CGI::Fast module
* a webserver with CGI or FastCGI support

Apache's mod_rewrite (or similar when using another server) is
recommended, but not required.

Note that some plugins may require additional modules or even external
programs to be available, check the documentation of the plugins for

Important: Plox uses the UTF-8 encoding everywhere, so make sure that
every file - templates, blog entries, even the source files if you want
to modify them - are saved as UTF-8.

3. Installation

These instructions assume you are using an Apache HTTP server. For other
servers, instructions and configuration directives may differ, please
consult your server's manual. Note that .htaccess options may also be
set globally in Apache's main configuration file.

Copy the contents of either the CGI or the FastCGI directory from this
distribution to a directory that can be accessed via the webserver (this
is usually a directory beneath the DocumentRoot).

Set the executable bit for the CGI/FastCGI script (either plox.cgi or
plox.fcgi), eg. «chmod 755 plox.fcgi», or using your FTP client.

The execution of CGI scripts must be enabled for the directory, eg. by
using the «Options +ExecCGI» directive in a .htaccess file.

You also need to add a handler for the scripts in .htaccess, either
«AddHandler cgi-script .cgi» or «AddHandler fastcgi-script .fcgi»,
depending on the script version you use.

For further questions regarding the setup of the server, please consult
the server's documentation.

There are .htaccess files included in this distribution, if you use
these, the Plox script will also act as a directory index (i.e. it will
be run when no specific file is requested) and it will handle all
requests for files (or directories) that do not exist in the file
system, mod_rewrite is required for this to work. This is a recommended
setup, you will still be able to use Plox without these settings, but
the URLs must include the script name in this case.

Now you need to copy the Plox modules and flavour templates and create a
directory for the blog entries: copy the contents of the Plox directory
to your server, it is not required to put these in a client-accessible
directory (i.e. the server should not serve these files).

Now modify the CGI script you copied earlier, and change the line
«use lib '/path/to/modules';» to point to the directory of the Plox
modules (the Plox/perl directory, ie. the directory where the file
Plox.pm can be found).

All further configuration is done by editing the Config.pm file (in the
Plox directory in your perl directory). See that file for details.

NOTE: The version of Config.pm in the Plox/perl/Plox directory contains
useful information for developers, but is not recommended for end users.
Instead, end users should use the Config.pm file from the Tools
directory (you need to copy it to the Plox/perl/Plox directory,
overriding the old file).

After that, Plox should be ready to use. If you have any further
questions, please feel free to contact the author.

4. Usage

To post a new blog entry - also called story from now on - simply place
a file in your data directory (as configured in the Config.pm file). The
format of the file is simple, eg.:

Title of the story…
header1: some additional data…

This is the actual text of the story…

The first line of the file is the story title, it must not be empty.

After the title, you may include arbitrary header data, this can be used
in the template. The header format is «header-name: header-value», the
«header-name» must only include alphanumeric characters, dash and
underscores. If a «header-name» is specified more than once, the
different values are joined with newlines. Headers are completely

The title (and headers, if any) and the story text must separated by an
empty line. The story text may be empty.

The name of a story file must contain only alphanumeric characters, dash
or underscore, and it must end with the configured extension.
Subdirectories of the data directories (with same restrictions on their
names, except the extension) may be used to create categories for your

Some examples, it is assumed that /data-dir is your data directory,
.txt is the extension of story files:

/data-dir/entry_1.txt       => http://example.org/entry_1.html
/data-dir/stuff/entry_2.txt => http://example.org/stuff/entry_2.html

If you can't use the provided rewrite rules, you may have to include the
CGI script's name, eg. <http://example.org/plox.fcgi/stuff/entry2.html>.

The requested URL's file extension specifies the flavour of the page to
generate. See the flavour directory for an example XHTML and an Atom
flavour. To create new flavours create a new template and include it in
the configuration.

If no specific file is requested, or the file index.<flavour> is
requested, an index page will be generated, containing all stories for a
specific category, subject to configured restrictions like number of
entries, for example <http://example.org/> shows all stories for main
category and its subcategories (can be changed in the configuration),
<http://example.org/xyz/index.html> show stories for the "xyz" category
and its subcategories.

These index pages can also be restricted to a specific date:
<http://example.org/2008/07/06/stuff/index.html> will show stories in
category stuff (and its subcategories unless configured otherwise)
posted on July 6th, 2008. To display the whole month use <…/2008/07/…>,
the whole year can be displayed with <…/2008/…>.

Important: This actually means that you can not create a top level
category with a name like 2008 (or anything else that looks like a valid
year). For users of Blosxom: Plox requires the date to be specified
before the categories for practical reasons, so date URLs from a Blosxom
installation will not work with Plox (though this could be fixed by a

I won't go into more details here, please take a look at the examples
provided with this distribution. For any questions, feel free to contact
the author.

5. License

Copyright 2009-2011, 2014 Stefan Goebel - <plox —at— subtype —dot— de>

Plox is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your
option) any later version.

Plox is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.

You should have received a copy of the GNU General Public License along
with Plox. If not, see <http://www.gnu.org/licenses/>.