README

   1
   2 blitiri - A single-file blog engine
   3 ===================================
   4
   5 blitiri is a single-file blog engine, written in Python_ and using
   6 reStructuredText_ for the entries markup.
   7
   8 It's licenced under the BOLA_ license, which is pretty much the same as public
   9 domain. Read the *LICENSE* file for more information.
  10
  11
  12 Installing blitiri
  13 ------------------
  14
  15 First of all, you need a webserver. Put ``blitiri.cgi`` in a directory where
  16 CGI is allowed.
  17
  18 Then, create a data directory, where you will store your articles.
  19
  20 Finally, configure blitiri by either copying the ``config.py.sample`` as
  21 ``config.py`` to the same directory where you put ``blitiri.cgi``, or editing
  22 the values inside ``blitiri.cgi``. The former is recommended to simplify
  23 updates.
  24
  25
  26 Using blitiri
  27 -------------
  28
  29 blitiri manages a database where it knows about your posts and the times they
  30 were created and updated. You manage the database by running ``blitiri.cgi``
  31 from the command line. The database is stored in the data directory.
  32
  33 Let's use an example to see how we can make a post. I'll assume you chose
  34 ``/home/me/blog/data/`` as your data directory, and your ``blitiri.cgi`` is at
  35 ``/home/me/web/blitiri.cgi``.
  36
  37
  38 First of all, pick a file name inside your data directory; we'll use
  39 ``/home/me/blog/data/test.rst`` as an example, but you can name it whatever
  40 you want. As long as it's inside the data directory (it can be inside a
  41 subdirectory too), blitiri doesn't care.
  42
  43 Write this inside::
  44
  45         Title: Test post
  46         Tags: test, tag
  47
  48         Hello world!
  49
  50         This is my first post!
  51
  52
  53 The format is very simple: first, any number of lines setting special
  54 attributes like *Title*, *Tags* (comma separated) and *Author* (if omitted,
  55 defaults to the one specified in the configuration). Then an empty line, and
  56 then the content in reStructuredText_ syntax.
  57
  58 In that case, the first two lines are special for blitiri: you specify the
  59 article's title and tags. Then, after the empty line, all the contents are
  60 interpreted directly as reStructuredText, and blitiri does not touch them in
  61 any way.
  62
  63 Now, you need to add that post to the database::
  64
  65         /home/me/web/blitiri.cgi add /home/me/blog/data/test.rst
  66
  67
  68 That's it!
  69
  70 To remove the post from the database (but keep the file), run::
  71
  72         /home/me/web/blitiri.cgi rm /home/me/blog/data/test.rst
  73
  74
  75 If you want to update a post (only updates the "updated time", the contents
  76 are updated on the fly), use::
  77
  78
  79         /home/me/web/blitiri.cgi update /home/me/blog/data/test.rst
  80
  81
  82 Personalizing templates
  83 -----------------------
  84
  85 If you don't like the default look, you can write your own templates for
  86 blitiri. This needs to be properly documented, but it's very obvious when you
  87 look at the code.
  88
  89
  90 Complaints and suggestions
  91 --------------------------
  92
  93 If you have any questions, suggestions or comments, please send them to me,
  94 Alberto Bertogli, at albertito@gmail.com.
  95
  96
  97 .. _Python: http://www.python.org/
  98 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
  99 .. _BOLA: http://auriga.wearlab.de/~alb/bola/
 100