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

Installing is as simple as, "tar xzvf nanoblogger-XXX.tar.gz -C $HOME", where "XXX" equals the version number and "$HOME" is a special shell variable that expands to your home directory, e.g. /home/foo.

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_CMD variable must contain backquotes e.g. DATE_CMD=`date` or DATE_CMD=`date '+%B %d %r'`

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.
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
entries.htm controls look of your blog entries
main_index.htm controls look of the blog's main page
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 entrie's content
$NB_EntryDate entrie's posted time
$NB_EntryPermalink entry's permalink
$NB_EntryTitle entrie'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 and 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.

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 in the included templates):
plugins description placeholders special requirements
auto_format.sh automatically adds paragraph tags to blank lines $NB_EntryBody none
blog_status.sh makes blog statistics $NB_Blog_Status none
calendar.sh uses cal to make a calendar with links $NB_Calendar cal
fortune.sh uses fortune to generate random quotes $NB_Fortune fortune
list_entries.sh makes list of entries recent or old $NB_Recent_Entries, $NB_Older_Entries none
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 a Blog to a Remote Web Site

Secure Shell:
If you have secure shell access to a remote web site, then you could use scp to update your blog or you could even install NanoBlogger on the remote site and run it from there.

FTP:
If you have FTP access to a remote web site, then you may want to use recursive directory uploading in your FTP client to update your blog, but as your blog grows in size this may not be the best solution. To minimize the amount of files I uploaded, I wrote a small shell script, that uses "ncftp" and "ncftpput" to update my blog with just the minimum of required files:

--

#!/bin/sh
# WARNING! the following commands could expose your password to another user viewing the output of "ps" or "top"
# remove old archives to conserve space
#echo "rm -fr /blog/archives" | ncftp -u XX -p XX myblog.com

# connect once to upload the main page and other misc. stuff
ncftpput -u XX -p XX -mR myblog.com /blog /home/XX/myblog/index.* \
   /home/XX/myblog/blog_style.css

# then connect again for the archives since we can only specify one path at a time
ncftpput -u XX -p XX -mR myblog.com /blog/archives /home/XX/myblog/archives/monthly

# End of script
--

Tips and Tricks

Credits

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

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

1. http://www.ibiblio.org/propaganda/microblogger