Introduction¶

blackblog is a very simple flatfile cms/blog very loosely influenced by blosxom ( http://www.blosxom.com/ )
this first version was written within a few hours, so please do not expect something
to fancy for now. it was first of all written for myself. ( http://startx.plentyfact.org where you will
find only some article stubs for now.)

it is very simple, in fact it consists of less then 400 lines of code so far. it does not use any database
and does not require cgi.

getting the code¶

the current version is 0.3.1

download: http://projects.plentyfact.org/attachments/download/13/blackblog-0.3.1.tar.gz

changelog: http://projects.plentyfact.org/repositories/entry/blackblog/trunk/doc/changelog

or grep the code from the repository:

svn checkout http://svn.plentyfact.org/blackblog

what else you will need¶

blackblog is written in lua, therefore - of course - you will have to install a lua interpreter on
your system. it will also require the cosmo tenmplate module. on debian or ubuntu

apt-get install lua5.1 liblua5.1-cosmo0

should do the trick.

setup¶

1. if you checked out the code from svn, change into blackblog/trunk/src and you will see some directories:

bin  config  data  lib  public  view

bin/           is where you find the blackblog script itself
config/        is the location of your blackblog.conf
lib/           that is where the blackblog lua module is placed
public/        the public web root
view/       
    templates/ the template directory

1. edit the blackblog.conf in the config/ directory.

you only need to adjust two settings:

   - install_dir          is the path to your installation directory
   - base_url             is the domain name of your blackblog, this is needed for the rss feed

3. now change into bin/ and run

$./blackblog

4. configure the webserver of your choice so document root points to
your public/ directory

5. now open the page in your browser and you should see the default welcome page

this is all for the start, as i said, simple. :)

writing articles¶

articles are simple text files in the data/ directory.
a simple article could look like this:

TITLE: welcome
DATE: 2010-11-27 12:30

BODY:
Obviously this is a default installation of blackblog.

it is probably quite obvious how it works: you can set the title and date of the article.
TITLE and DATE are the only required tags.

everything after the BODY: tag will be parsed as bbcode, however, empty lines will be kept and
automatically replaced by "<br />".

writing longer articles (teasers for the front page)¶

if you write a longer article, you might only want a short teaser to appear on the startpage. teasers will
be generatet automatically ( see CONFIG.teaser_lenght in the config file), or you can define the break point
manually:

TITLE: a longer article
DATE: 2010-11-27 20:10

BODY:
Obviously this is a default installation of blackblog, but this is a bit more 
then a short text, it is a bit longer , therefore i better stop the teaser
here :BREAK: Now i tell you the whole story...(etc)

There are two different "tags" you can use to seperate a teaser from the rest of the article:

The tag :BREAK: will define where your startpage teaser ends.

The tag :BREAKDROP: will do the same, but the teaser text (the text before :BREAKDROP: will not be repeated on
the article page.

If you use any tag in an article, CONFIG.teaser_lenght will be used automatically.

pathes¶

pathes: if the article is e.g. saved as intro.txt in data/articles/, blackblog will later render this to
http://mywebsite.org/articles/intro.html

categories¶

the pathes also serve as categories, where e.g. /tech is considered a category. blackblog will automatically
create an index page /tech/index.html

body markup¶

blackblog uses an extended version of of bbcode. blackblog will automatically convert the code into valid XHTML.
see here for a list of currently supported tags.

what happens when you run ./blackblog¶

when you run the script, blackblog will render html pages from the text files in the data/ directory
and keep the pathes, but it will do two more nice things: it will create a overview page ( http://mywebsite.org/index.html )
where the articles are listed (sorted by date) and create an rss xml file ( http://mywebsite.org/rss.xml )

that is all it does for now, however, more features in the future are possible.

styling¶

blackblog is based on templates in the templates/ directory, there is also a style.css in public/ .

if you wonder why¶

well, static html still rules. also, you might want to have your actual blackblog installation on your laptop, and only
occasionally push the file to the server to update your website. it is actually quite nice to write your articles with
an local desktop editor or something like zim ( zim-wiki.org ) . you can, just as an idea, of course also use a versioning
system such as git or svn to manage your data/ directory. and first of all, it is simple.

is it webscale?¶

hell , i knew you would ask that.

blackblog

Wiki