NanoBlogger Manual

by n1xt3r (Kevin R. 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, from the command line type "tar xzf nanoblogger-XXX.tar.gz where "XXX" equals the version number.

Requirements

The ability to use a command line interface and perhaps something to rant about. =)

programs required other than bash:
cat, cp, cut, date, echo, eval, expr, getopt, getopts*, grep (fgrep), mkdir, read, rm, sed, shift*, sort, touch, trap, uname
* = only used if output from uname is not "Linux"

Usage

NanoBlogger is designed to work offline, but the contents created are intended to be published online. To create a blog, run NanoBlogger with the name or path that will identify your blog. This will be known as your local path. 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: "Uploading a blog to a remote web site".

Synopsis

nb [OPTION]... [PATH_TO_BLOG]...
Try "nb -h" to see 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.

How Blogging Works

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 feautures "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, like from a plugin. Allowing for a certain amount of modularity with server-side scripting langauages 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. Full permalinks can be enabled in blog.conf, by toggling the variable FULL_PERMALINKS on.
The blog's appearance is controlled by the following templates:
templates description
archive_links.htm the links to the archives
default.htm controls look of alternate pages, such as the archive pages and permalinks
entries.htm controls look of your blog entries
main_index.htm controls look of the blog's main page
permalink.htm controls look of a blog entry inside it's permalink page (similar to entries.htm)
rdf_entries.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_EntryBody entry's content
$NB_EntryDate entry's posted time
$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_Entries all the current entries
All the placeholders are reinterpretted by the shell as variables when a template is sourced, making the templates capable of a few bash 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. How cool is that!? This greatly enchances the power of the templates, making it possible to create your own script and replace my "`date`" example with "`your_script`". Have fun!

How Plugins Work

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
autoformat/auto_space.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 uses cal to generate a calendar with links $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
To disable a plugin, rename the plugin's extension from ".sh" to ".off". This will move the plugin off of the radar, so to speak.

Uploading 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 myblog"

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

Tips and Tricks

Adding Comment support to Your Blog

There's many ways you could accomplish this, but I chose to go with a perl based solution, because most web server's already support it. The program I found is called CGIComment [1] and was fairly easy to integrate into my blog. I like CGIComment becuase it adds the comments to the bottom of any HTML document, it's very flexible, and easy to modify it's appearance. CGIComment has it's own configuration and documentation and is easy to setup. For the purpose of this document, though, I will take you through the steps I went through to get everything to work server-side: With these steps we've added comment support to our blog, more importantly we defeated the use of javascript to display a count of comments by each entry. It's now done server-side and thus, much, much faster!

Credits

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

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

1. http://triskam.virtualave.net/cgicomment.html
2. http://www.ibiblio.org/propaganda/microblogger