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 for the command line. It uses common unix tools, such as cat, grep and sed. It's free to use and modify under the GNU General Public License.

Synopsis

nb [-b blogdir] [options]

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.

Upgrading

When upgrading nanoblogger, there's three basic things that need to be considered: archives, templates, and configuration. These three things also 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:
bash, cat, cp, cut, dirname, date, expr, grep, mkdir, mv, read, rm, sed, sort, touch, trap

Getting Started

Creating a New Blog
To create a new blog invoke:
nb --blogdir myblog_dir --add
where "myblog_dir" is a non-existant directory. This is will create a new directory, copy the default files over, and then let you edit the blog's configuration. Run the same command again to add another entry.

Settings and Configuration

To edit the blog's configuration invoke:
nb --blogdir myblog_dir --configure
This opens blog.conf from the blog directory for editing.

Setting the Editor

The editor defaults to the EDITOR variable in your shell's environment, but falls back on vi when no EDITOR is set. You can specify a different editor to use by overriding EDITOR in blog.conf or setting the EDITOR variable in your shell's environment.

Setting the Date Format for New Entries

DATE_FORMAT controls the look of a new entry's date. The default DATE_FORMAT uses "%B %d, %Y %l:%M %p" and produces something like this: "August 05, 2003 12:53 AM". You can also specify the locale to be used for date command (see the variable DATE_LOCALE). Please note that this setting has no effect on previous entries. Read the man pages of the date command to see more on how to customize the format of the date command's output.

Setting the Web Address

BLOG_URL is used as the address for the blog. Typically, you would set this to a remote address such as: "http://myblogurl.com". Replacing myblogurl.com with the actual address to your blog.

Setting the Link for "Main"

BLOG_URL_MAIN is used as the navigational link for "main". The default is set to "$BLOG_URL/index.html", for easier local navigation.

Setting the Style Sheet

BLOG_CSS is used as the link to the style sheet in the default set of templates. It provides an easy way to edit or switch the style sheet's location without having to edit each template. It should be set in a similar fashion to BLOG_URL_MAIN, 'BLOG_CSS="$BLOG_URL/styles/nb_rusted.css"'. Style sheets are located in the styles directory.

Setting the Author's Name

BLOG_AUTHOR can be used to set the author's name, the default is to set the author's name using the common USER variable. Setting BLOG_AUTHOR will override this behavior.

Setting the Number of Entries to Display

MAX_ENTRIES sets the maximum number of entries that get displayed as current. This must be set to a number higher than zero.

Toggling the Display of Permalinks

PERMALINKS toggles display of permalinks along-side an entry. The default is set to "1", display permalinks.

Building Individual Archives for Each Entry

Setting ENTRY_ARCHIVES to equal "1", enables individual archiving of each entry and reconfigures the links of the entries to point to their individual archives. Note that this will increase the rebuild time since more pages will have to be generated.

Setting Actions for Previewing and Publishing

BLOG_PREVIEW_CMD and BLOG_PUBLISH_CMD may both be set to a custom command to run when invoked by their respective options, --preview and --publish.

Global Configuration

NanoBlogger has it's own configuration file, nb.conf that holds settings which effect all blogs. The global configuration file is read first meaning that settings in the blog's configuration may override settings in nb.conf. Typically one would set BLOG_DIR here as a default blog directory to use. This configuration is also looked for under the file, $HOME/.nb.conf.

Templates and Placeholders

Templates are located in the blog's sub-directory, templates.
The blog's appearance is controlled by the following templates:
templates description
category.htm controls look of the categories pages
entry.htm controls look of your blog entries
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
permalink.htm controls look of an entry's archive page
permalink_entry.htm controls look of an entry within it's archive page
* = used by plugin
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_EntryDescription entry's description
$NB_EntryID entry's id
$NB_EntryPermalink entry's permalink
$NB_EntryTitle entry's title
* = generated by plugin
The main template includes the following placeholders:
placeholders description
$BLOG_CHARSET blog's character set
$BLOG_URL_MAIN blog's "main" link
$BLOG_CONTACT blog's contact info
$BLOG_DESCRIPTION blog's description
$BLOG_TITLE blog's title
$BLOG_URL blog's URL
$NB_Month_Links* links to the monthly archives
$NB_Category_Links* links to categories
$NB_Main_Links* user defined links
$NB_Entries all the current entries
* = generated by plugin

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
DESC: the description of this entry
-----
BODY:
This is my new entry ...
-----
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.

Plugins

Types of Plugins

Regular Plugins

Regular plugins are stored in the plugins directory and are loaded first.

Archive Plugins

Archive plugins are stored in the plugins/archive directory and are loaded when the archives are built.

Monthly Plugins

Monthly plugins are stored in plugin/archive/monthly directory and are loaded for each month.

Entry Plugins

Entry plugins are stored in the plugins/entry directory and are loaded for each entry processed.

Postformat Plugins

Postformat plugins are stored in the plugins/postformat directory and are loaded after each page generated.
Plugins typically work by creating placeholders for the templates, but are in no way limited to creating placeholders. Placeholders allow for 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. Some plugins may require you to identify it's unique placeholder/destination and manually add it to your templates.
The main plugins (most are enabled by default):
plugins description variables targets notes
archive/master_index.sh creates a master index page of the archives none $BLOG_URL/archives.html requires makepage.htm template
archive/monthly/monthly_cal.sh adds a calendar with links for each active day none $NB_Monthly_Calendar requires cal
atom.sh adds an atom feed LIMIT_ITEMS $BLOG_URL/atom.$NB_SYND_FILETYPE none
blog_links.sh generates some useful links none $NB_Main_Links, $NB_Month_Links, $NB_Category_Links requires main_links.htm template
blog_status.sh generates some statistics none $NB_Blog_Status none
calendar.sh adds a calendar with links for each active day none $NB_Calendar requires cal
entry/auto_break.sh converts blank lines to html paragraph breaks AUTO_FORMAT $NB_EntryBody none
entry/moods.sh converts mood variables into equivalent images AUTO_FORMAT $NB_EntryBody copy moods directory to blog's directory
fortune.sh generates random quotes FORTUNE_FILE $NB_Fortune requires fortune
list_entries.sh adds links to recent or old entries LIST_N, LIST_OFFSET $NB_Recent_Entries, $NB_Older_Entries none
mymood.sh adds ability to display your mood none $NB_My_Mood copy moods directory to blog's directory
postformat/tidy.sh validates HTML code TIDY_ARGS $NB_Tidy requires tidy
rss.sh adds rss feeds LIMIT_ITEMS $BLOG_URL/index.$NB_SYND_FILETYPE, $BLOG_URL/$ARCHIVES/cat_n.$NB_SYND_FILETYPE none
To disable a plugin, rename the plugin's extension from ".sh" to ".off".

Publishing 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, Paul Drain <pd_at_cipherfunk.org>, Pavel Janik <Pavel_at_Janik.cz>, and O.R.Senthil Kumaran <orsenthil_at_users.sourceforge.net> for all the contributions 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://freshmeat.net/projects/cgicomment/
3. http://freshmeat.net/projects/microblogger