NanoBlogger Manual

by n1xt3r (Kevin Wood)


This document explains how to install and use NanoBlogger.


Table of Contents

Introduction

NanoBlogger is a small weblog engine written in Bash that uses common unix tools, such as cat, grep and sed. It's free to use and modify under the GNU General Public License.

Features

Installation

To install nanoblogger, download the tar archive from the web site[1]. Then from the commandline type "tar xzf nanoblogger-XXX.tar.gz where "XXX" equals the version number. You will need to edit the BASE_DIR variable if it's not installed to your home directory or if you decide to change it's location.

Upgrading

When upgrading nanoblogger, there's three basic things that need to be considered, and they are: archives, templates, and configuration. These are the three things that should be backed up and may require some minor adjustments before they work well with the new version. Here are some steps you can take to help ease the transition.

Requirements

programs required other than bash:

cat, cp, cut, date, expr, grep, mkdir, read, rm, sed, sort, touch, trap

For online publishing you'll need some kind of shell or FTP access to your web server.

Usage

NanoBlogger is designed to work off-line, but the contents created are intended to be published online. To create a blog, use nb --blogdir myblog --add. Where "myblog" is the local path to your new blog. This is will setup a new directory and open the blog's configuration for editing. To setup your blog for a remote site, edit the blog's BLOG_URL variable to point to the remote path, then refer to the section: "Publishing a blog to a remote web site" for further details.

Synopsis

nb [-b blogdir] [options]
Try "nb --help" for all available options.

For each blog there's a user defined configuration file called "blog.conf". This file controls the behavior of a blog. It allows you to change such things as, how many entries to display on the front page. It's also where you set the title, description, and the URL for your blog. The DATE_FORMAT variable can be customized to change the date format of a new entry. The default DATE_FORMAT uses "%B %d, %Y %l:%M %p" and produces something like this: "August 05, 2003 12:53 AM". Read the man pages of the date command to see more on how to customize the format of a date.

Building The Blog

Entries are kept inside the blog's "archives" directory as time-stamped filenames. NanoBlogger uses the filename to determine how to sort the entries into the archives.

NanoBlogger features "clippings", which is a directory consisting of the parts that build your blog. They contain preformatted versions of your recent entries as well as other things that might be part of your blog, e.g. output from a plugin. Thus, allowing for a certain amount of modularity with server-side scripting languages such as PHP, for further processing.

NanoBlogger creates the following web pages:
The web pages are regenerated each time you add, edit, or delete an entry.

Enabling full permalinks, causes each entry to have it's own web page. To enable full permalinks in your blog, edit blog.conf and set FULL_PERMALINKS equal to 1. Make sure that the permalinks have been generated, you may have to rebuild your blog. The entries' permalinks should've automatically been changed, if you experience any problems, have a look at the "entry.htm" template. Look at the "href" line and make sure that it's only set to equal "$NB_EntryPermalink". If it's not then change it and rebuild your blog again.

The blog's appearance is controlled by the following templates:
templates description
archive.htm controls look of the master archive page
archive_links.htm controls look of the master archive links
category.htm controls look of the categories pages
category_links.htm the links to the categories
entry.htm controls look of your blog entries
entry_links.htm controls look of the entry links
entrycat_links.htm controls look of the entry category links
main_index.htm controls look of the blog's main page
main_links.htm contains user defined links
makepage.htm default template used by makepage option
month_archive.htm controls look of the monthly archive pages
month_links.htm controls look of the monthly archive links
permalink.htm controls look of the permalink pages
permalink_entry.htm controls look of a blog entry within a permalink page
rdf_entry.xml controls look of each individual news item in the rss feed
rdf.xml controls look and format of rss feed (index.rdf)

In addition there's a stylesheet called, "blog_style.css".
The entry template includes the following placeholders:
placeholders description
$NB_EntryAuthor author of entry
$NB_EntryCategories entry's category links
$NB_EntryBody entry's content
$NB_EntryDate entry's posted time
$NB_EntryID entry's id
$NB_EntryPermalink entry's permalink
$NB_EntryTitle entry's title

The main template includes the following placeholders:
placeholders description
$BLOG_CHARSET blog's character set
$BLOG_CONTACT blog's contact info
$BLOG_DESCRIPTION blog's description
$BLOG_TITLE blog's title
$BLOG_URL blog's URL
$NB_Archive_Links links to archives
$NB_Category_Links links to categories
$NB_Main_Links user defined links
$NB_Entries all the current entries
All the placeholders are reinterpreted by the shell as variables when a template is sourced, making the templates capable of a few shell scripting tricks themselves. As a simple example, you could place this in your template: "Last Modified: `date`", and it would display the time your page was last modified, using the date command. Thus greatly enhancing the power of the templates, making it possible to create your own script and replace my "Last Modified" example with your own script.

Format of an Entry

The entry format is made up of pieces of metadata. Each piece of metadata is of the format KEY: VALUE, then a carriage return that separates one piece from the next. The order of the metadata pieces is not important.

Example:

TITLE: A New Entry
AUTHOR: foo
DATE: January 30 2004, 12:00 PM
-----
BODY:
This is my new entry ...
-----

Plugins

Plugins work by creating placeholders for the templates, allowing a great deal of control in how the plugins output is placed in the template. The variable, ENABLE_PLUGINS, in blog.conf toggles the use of plugins on/off. Create plugins that run specifically for your blog by creating a "plugins" directory under a blog's own directory and copying or creating a plugin with the ".sh" extension.

Additionally there are some plugins specific to the formatting of entries, and are referred to as auto-format plugins, which allows for automatic placement of HTML elements, such as placing paragraph breaks inside blank lines. The variable, AUTO_FORMAT, in blog.conf toggles this feature on/off, but requires ENABLE_PLUGINS to be toggled on.

To use a new plugin, you need to identify it's unique placeholder and add it to your template.

The plugins included and what placeholders they create (most are enabled by default and setup in the templates):
plugins description placeholders special requirements
archive/monthly_cal.sh adds a calendar with links to each monthly archive $NB_Monthly_Calendar cal
autoformat/auto_break.sh adds paragraph breaks to blank lines of entries $NB_EntryBody none
autoformat/moods.sh adds ability to use mood variables inside a blog's entry $NB_EntryBody copy moods directory to blog's directory
blog_status.sh generates blog statistics $NB_Blog_Status none
calendar.sh adds a calendar with links based on the current month $NB_Calendar cal
fortune.sh uses fortune to generate random quotes $NB_Fortune fortune
list_entries.sh generates list of entries recent or old $NB_Recent_Entries, $NB_Older_Entries none
mymood.sh adds ability for user to set a mood status in their blog $NB_My_Mood copy moods directory to blog's directory
postformat/tidy.sh validates HTML code $NB_Tidy HTML tidy
To disable a plugin, rename the plugin's extension from ".sh" to ".off". This will move the plugin off of the radar, the next time NanoBlogger is run.

Publishing Your Blog to a Remote Site

FTP:
Any FTP client should do, but I'd recommend ncftp. Be sure to use recursive mode when uploading your blog directory. e.g. "ftp myblog.com, put -r [your_blog_dir]"

Other methods:
If you're not limited to FTP, you might want to consider SSH (scp, sftp, etc.), rsync or WebDAV.

Tips and Tricks

Credits

Thanks to Adrien "ze" Urban for many code enhancements and suggestions.

Thanks to Bowie J. Poag, author of MicroBlogger [3], for the inspiration of this project.

1. http://home.columbus.rr.com/n1xt3r/downloads/
2. http://triskam.virtualave.net/cgicomment.html
3. http://www.ibiblio.org/propaganda/microblogger