NanoBlogger User Manual

by n1xt3r (Kevin Wood)

This document explains how to install and use NanoBlogger.

Table of Contents

1. Introduction
2. Features
3. Installation
4. Requirements
5. Getting Started
6. Settings and Configuration
7. Managing Entries and Categories
8. Templates
9. About Plugins
10. Writing Plugins
11. Publishing
12. Adding Support for Comments
13. Importing Entries The Hard Way
14. Tips and Tricks
15. Credits

1. 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 to create static HTML content. It's free to use and modify under the GNU General Public License.

Synopsis

 
nb [-b blog_dir] [options]
        

2. Features

3. Installation

To install nanoblogger:
1. download the gzipped tar archive from the web site[1]
2. decompress the gzipped tar archive (where "XX" equals the version number):
        tar xzf nanoblogger-XX.tar.gz
        

Upgrading

IMPORTANT: Please refer to this documentation and any related changelogs to see what has changed. Any differences between your setup will have to be resolved manually. Simply copying your old templates and configuration will only cause problems. The simplest way to upgrade is described below.

Three basic steps to upgrading (from the shell prompt):

1. create a new weblog directory using nanoblogger (skip the configuration):
        nb [-b blog_dir] -a

2. copy the old data directory over to the new weblog directory:
        cp -r [old_blog_dir]/data [newblog_dir]

3. edit the new blog.conf to your likings and rebuild the weblog:
        nb [-b blog_dir] --configure -u all
        

4. Requirements

Programs:

Bash (at least v2.05), cat, cp, cut, dirname, date*, expr, grep, mkdir, mv, read, rm, sed, sort, touch, trap

* = GNU version recommended, but not required

5. Getting Started

Creating a New Weblog

To create a new weblog from your shell prompt:

cd [nb_dir]
./nb --blogdir [myblog_dir] --add
        
where nb_dir is the path that NanoBlogger was installed to and myblog_dir is a nonexistent directory. This will create a new directory, copy the default files over, and then let you edit the weblog's configuration. Multiple weblogs can be created this way. Running the same command again on an existing weblog directory will add a new entry.

For faster and easier invocation try adding "nb" to your shell's path or aliases (see shell's manual).

To set a default weblog directory:

1. edit either nb.conf or $HOME/.nb.conf.
2. set BLOG_DIR to your weblog directory:
        BLOG_DIR="$HOME/public_html/[myblog_dir]"
        

6. Settings and Configuration

To edit the weblog's configuration invoke:
nb --blogdir [myblog_dir] --configure -u all
        
This opens blog.conf from the weblog directory for editing and updates the entire weblog.

Setting the Browser

The browser defaults to the BROWSER variable in your Bash environment, but falls back to "lynx", when no BROWSER is set. You can specify a different browser to use by overriding BROWSER in blog.conf or setting the BROWSER variable in your Bash environment. In Mac OS X, you would set this to "open".

Setting the Editor

The editor defaults to the EDITOR variable in your Bash environment, but falls back to "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 Bash environment.

Setting the Date Format for New Entries

DATE_FORMAT specifies the date format to use for new entries. The default is to use the output from the date command. You can also specify the locale to be used for date command (see the variable DATE_LOCALE). You can specify additional command line arguments with DATE_ARGS, useful for specifying time in UTC. Please note that these settings have no effect on previous entries. Read the man pages of the date command to see how to customize the format of the date command's output.

Examples:

DATE_FORMAT="%m.%d.%Y %H:%M"
DATE_LOCALE="$LANG"
DATE_ARGS="-u"   

Setting the Timezone for Syndication Feeds

BLOG_TZD sets the timezone for your weblog's syndication feeds. The default is to set this automatically using, "%z", a non-standard extension of the date command. You'll have to set this manually, if the date command on your system doesn't support it or see if your system administrator will install GNU date for you.

Example:

BLOG_TZD="-0:500"
   

Setting the Encoding

BLOG_CHARSET sets the character encoding to be used for your weblog.

Example:

BLOG_CHARSET="iso-8859-1"

WARNING: If you have the Tidy plugin enabled, this setting will be overridden by Tidy. Please, refer to Tidy's documentation for setting the character encoding.

Setting the Mime Type

BLOG_MIMETYPE sets the mime type to be used for your weblog.

Example:

BLOG_MIMETYPE="text/html"
   

Setting the Web Address

BLOG_URL should be set as the full URL to your weblog excluding the index file and any preceding "/". This setting is required for absolute links and syndication feeds.

Example:

BLOG_URL="http://my-site.com/weblog"
   

Setting the Style Sheet

BLOG_CSS sets the style sheet to be used by your weblog. Style sheets are located in the styles directory.

Example:

BLOG_CSS="styles/nb_rusted.css"

Setting the Favorite Icon

BLOG_ICON sets the favorite icon to be used by your weblog. Favorite icons are located in the images directory.

Example:

BLOG_ICON="images/favicon.ico"

Toggling the use of Absolute Links

ABSOLUTE_LINKS enables the generation of absolute links. Defaults to "0", disabled.

Setting the Link for a Directory's Index

NB_INDEX determines how a directory's index is accessed. The default is to leave this as blank.

Example:
NB_INDEX="index.html"
   

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 Maximum Number of Entries to Display on the Main Page

MAX_ENTRIES sets the maximum number of entries that get displayed on the main page. Defaults to "10".

Setting the Maximum Number of Entries to Display for Each Page

MAX_PAGE_ENTRIES sets the maximum number of entries to display for each page. Defaults to "$MAX_ENTRIES".

Setting the Default Text Formatting

ENTRY_FORMAT specifies the default text formatting to use for an entry. Defaults to "raw".

Toggling the Display of Permanent Links

PERMALINKS toggles the display of an entry's permanent link. The default is to display permanent links.

Toggling the Building of Entry Archives

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

Special Category Archiving Preferences

CATARCH_DATATYPE determines the set of data to load for the category archives. There's two types of data that can be specified, "ALL" or "NOBODY".

ALL = full entry metadata (slow and bigger cache)
NOBODY = all except entry's BODY metadata (faster and smaller cache)
    

IMPORTANT: Please edit category_entry.htm accordingly.

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.

Setting the Cache Preferences

MAX_CACHE_ENTRIES sets the maximum number of entries to store in the cache. Defaults to "$MAX_ENTRIES".

Setting BLOG_CACHEMNG to "0" disables automatic management of the cache. The cache may be managed manually using the --update-cache command line option.

Toggling Interactive Mode

BLOG_INTERACTIVE toggles interactive mode for your weblog and has the same effect as the --interactive command line option. The default is "0" for disabled, setting to "1" will toggle the mode back on.

Changing the File Type

NB_FILETYPE specifies the file type or rather the suffix for the generated files. The default is set to "html".

Changing the Default Query Mode

QUERY_MODE specifies the default query mode for listing entries and displaying them on the main page. Defaults to "$MAX_ENTRIES".

Plugin Configuration

PLUGINS_DIR specifies the directory where plugins are located. The default is set to $NB_BASE_DIR/plugins. When specifying PLUGINS_DIR, keep in mind that many sub-directories are expected to exist. It may be easier to start by copying the plugins directory and sub-directories to the desired location.

Global Configuration

NanoBlogger has it's own configuration file, $NB_BASE_DIR/nb.conf that holds settings which effect all weblogs. The global configuration file is read first meaning that settings in the weblog's configuration may override settings in $NB_BASE_DIR/nb.conf. This configuration is also looked for under the file, $HOME/.nb.conf.

Changing the Default Language of NanoBlogger

NB_LANG is a global configuration variable that sets the language definitions to load. The default is "en" for English

Example:

NB_LANG="en"
    

7. Managing Entries and Categories

Commands to manage entries and categories.

Managing Entries

Entry ID's

The latest entry added, will always have an ID of "1", entry's added before that will have ID's of higher values. An entry will have a different ID for each category it belongs in. When modifying entries from a category, ID's for both category and entry must be specified.

Drafting Entries

Creating a new draft:

nb [-b blog_dir] --draft draft.txt
    

Importing the draft as a new entry:

nb [-b blog_dir] --file draft.txt -a
    

Creating Entries

Adding a new entry:

nb [-b blog_dir] -a
        
Adding a new entry to a category:
nb [-b blog_dir] -c 1 -a
        
Setting title and author for new entry:
nb [-b blog_dir] -t "New Entry" -n [entry_author] -a
        
Setting title, author, and body for new entry:
nb [-b blog_dir] -t "New Entry" -n [entry_author] -T "This is my message." -a
        
Importing new entry from file:
nb [-b blog_dir] --file draft.txt -a

Listing Entries

Listing current entries:

nb [-b blog_dir] -l
        
Listing all entries:
nb [-b blog_dir] -l all
        
Listing entries for a category:
nb [-b blog_dir] -c 1 -l
        

Editing Entries

Editing the last entry created:

nb [-b blog_dir] -e 1
        
Editing an entry from a category:
nb [-b blog_dir] -c 1 -e 1
        
Editing multiple entries:
nb [-b blog_dir] -e 1,2,3
        

Moving Entries

Moving an entry to a category:

nb [-b blog_dir] -c 1 -m 1
        
Moving an entry to multiple categories:
nb [-b blog_dir] -c 1,2,3 -m 1
        
Moving multiple entries to a category:
nb [-b blog_dir] -c 1 -m 1,2,3
        

Deleting Entries

Permanently deleting an entry:

nb [-b blog_dir] -d 1
        
Permanently deleting multiple entries:
nb [-b blog_dir] -d 1,2,3
        
Deleting an entry from a category:
nb [-b blog_dir] -c 1 -d 1
        

Changing Entry's Date

Specifying a new entry's date using the TIMESTAMP metatag:

nb [-b blog_dir] --tag TIMESTAMP --tag-text "YYYY-MM-DD HH:MM:SS" -a
    
Changing an old entry's date:
nb [-b blog_dir] --tag TIMESTAMP --tag-text "YYYY-MM-DD HH:MM:SS" -e 2
     
Manually changing an entry's date:
1. nb [-b blog_dir] -e 2
2. TIMESTAMP: YYYY-MM-DD HH:MM:SS
     
The date command must support the "-d" option for the date to follow the format set by "$DATE_FORMAT".

Managing Categories

Category ID's

Category ID's count up from "1". A category's ID remains constant until that category is deleted. Deleting a category will free up that category's ID for use by a new category upon creation.

Category Commands

Creating a new category:

nb [-b blog_dir] -c new -a
        
Setting the title for a new category:
nb [-b blog_dir] -t "New Category" -c new -a
        
Listing available categories:
nb [-b blog_dir] -l cat
        
Editing a category's title:
nb [-b blog_dir] -c 1 -t "News" -e cat
        
Deleting a category:
nb [-b blog_dir] -c 1 -d cat
        

8. Templates

Templates are located in the weblog's sub-directory, templates.

Special Template Characters

IMPORTANT: Escaping these characters prevents them from changing.

Special characters that effect the templates:
characters description notes
$ dollar sign prepend backslash to escape, e.g. "\$"
` back quote form of command substitution, prepend backslash to escape, e.g. "\`"
$( dollar sign and left parenthesis form of command substitution, prepend backslash to escape, e.g. "\$("

Default Templates

The weblog's appearance is controlled by the following templates:
templates description
category_archive.htm controls look of the category pages
main_index.htm controls look of the weblog'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
entry.htm controls look of the default archive entries
category_entry.htm controls look of the category entries
permalink_entry.htm controls look of the permanent archive entries
weblog_status.htm controls look of weblog status
year_archive.htm controls look of yearly archive pages
entry.metadata controls the format of the entry's metafile
file.metadata controls the format of a metafile

9. About Plugins

Plugins Framework

Regular Plugins: plugins

Regular plugins are initialized unconditionally.

Archive Plugins: plugins/archive

Archive plugins are initialized when the archives are updated.

Monthly Plugins: plugins/archive/month

Monthly plugins are initialized for each monthly archive that is updated.

Yearly Plugins: plugins/archive/year

Yearly plugins are initialized for each yearly archive that is updated.

Entry Plugins: plugins/entry

Entry plugins are initialized unconditionally for each entry that is updated.

Entry Modify Plugins: plugins/entry/mod

Entry Modify plugins are initialized for each entry that is modified.

Entry Formatting Plugins: plugins/entry/format

Entry Formatting plugins are initialized for each modified entry based on the FORMAT metadata field. More than one format may be specified using space or commas as a separator.

Page Plugins: plugins/page

Page plugins are initialized unconditionally before each page that is updated.

Page Formatting Plugins: plugins/page/format

Page Formatting plugins are initialized for each page that is updated based on the FORMAT metadata field. More than one format may be specified using space or commas as a separator.

Make Page Plugins: plugins/makepage

Make Page plugins are initialized after each page that is updated.

Post Plugins: plugins/post

Post plugins are initialized unconditionally for post-weblog related tasks.

Most plugins will operate on their own conditions once they've been initialized.

Default Plugins

Default plugins (most are enabled by default):
plugins description variables targets notes
archive/master_index.sh creates a master index page of the archives none $ARCHIVES_DIR/index.$NB_FILETYPE requires makepage.htm template
archive/month/month_calendar.sh generates a calendar with links for each active day none $NB_MonthlyCalendar requires cal
archives/year/year_index.sh generates yearly indexes of the archives none $ARCHIVES_DIR/$yearn/index.$NB_FILETYPE requires makepage.htm template
articles_meta.sh* generates articles from metafiles in the "articles" directory ARTICLE_DIRS, ARTICLE_FORMAT $NB_ArticleLinks requires makepage.htm template, plugin must be last to load
articles_text.sh* generates articles from text files in the "articles" directory ARTICLE_DIRS, ARTICLE_FORMAT $NB_ArticleLinks requires makepage.htm template, plugin must be last to load
atom.sh adds an atom feed LIMIT_ITEMS, ATOM_CATFEEDS, BLOG_FEED_LANG $NB_AtomVer, $NB_AtomFile, index-atom.$NB_SYND_FILETYPE none
calendar.sh generates a calendar with links for each active day CAL_CMD, CAL_ARGS $NB_Calendar requires cal
entry/category_links.sh generates category links none $NB_EntryCategories none
entry/excerpt.sh* creates an excerpt from entry's text none $NB_EntryExcerpt ends after first detected double line break (blank line)
entry/format/autobr.sh converts blank lines to HTML paragraph breaks none $NB_MetaBody, $NB_EntryBody FORMAT: autobr
entry/format/markdown.sh uses markdown to handle formatting none $NB_MetaBody, $NB_EntryBody FORMAT: markdown
entry/mod/base_url.sh helps set relative links %base_url% $NB_EntryBody example: <img src="%base_url%images/pic.png" />
entry/mod/moods.sh converts mood variables into smiley icons MOODS_URL $NB_EntryBody copy moods directory to weblog's directory
fortune.sh generates random quotes FORTUNE_FILE $NB_Fortune requires fortune
makepage/tidy.sh validates HTML/XML code TIDY_HTML_ARGS, TIDY_XML_ARGS $NB_Tidy, $BLOG_DIR/tidy.log requires HTML Tidy, overrides $BLOG_CHARSET
mymood.sh* adds ability to display your mood MOODS_URL $NB_MyMood copy moods directory to weblog's directory
page/feed_links.sh generates alt links for feeds none $NB_AtomAltLink, $NB_RSS2AltLink, $NB_RSSAltLink requires one of atom.sh, rss.sh, or rss2.sh plugins
page/page_links.sh regenerates links for inclusion on other pages none $NB_MainLinks, $NB_RecentEntries, $NB_CategoryLinks, $NB_MonthLinks, etc. requires one of weblog_links.sh or recent_entries.sh plugins
page/format/autobr.sh converts blank lines to HTML paragraph breaks none $NB_MetaBody, $NB_EntryBody FORMAT: autobr
page/format/markdown.sh uses markdown to handle formatting none $NB_MetaBody, $NB_EntryBody FORMAT: markdown
page/format/moods.sh converts mood variables into smiley icons MOODS_URL $NB_MetaBody, $NB_EntryBody may combine with with others e.g. "FORMAT: moods, markdown"
recent_entries.sh generates links to recent and old entries LIST_N, LIST_OFFSET $NB_RecentEntries, $NB_OlderEntries none
rss2.sh adds rss 2.0 feeds LIMIT_ITEMS, RSS2_CATFEEDS, BLOG_FEED_LANG $NB_RSS2File, index-rss.$NB_SYND_FILETYPE none
rss.sh adds rss 1.0 feeds LIMIT_ITEMS, RSS_CATFEEDS, BLOG_FEED_LANG $NB_RSSFile, index.$NB_SYND_FILETYPE none
weblog_links.sh generates some useful links ALL_YEARLINKS, MAX_YEARLINKS, ALL_MONTHLINKS, MAX_MONTHLINKS $NB_MainLinks, $NB_MonthLinks, $NB_CategoryLinks requires main_links.htm template
weblog_status.sh generates some statistics none $NB_BlogStatus requires weblog_status.htm template

* = actual name may vary.

To disable an individual plugin, rename the plugin's extension from ".sh" to ".off".

Writing Plugins

Tools for Developing Plugins

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. Some plugins may require you to identify it's unique placeholder/destination and manually add it to your templates.

To write a plugin, you should begin by creating a text file with the ".sh" suffix. plugins are basically shell scripts that get loaded (sourced in shell terms) depending on where the plugin is located in the plugins directory or one of the plugin sub-directories. It may be a good idea to look at a simple plugin, such as fortune.sh for an idea on how a plugin works. When the new plugin is saved, it needs to have the appropriate read permissions, so it can be loaded by NanoBlogger. Executable permissions are not necessary for plugins.

The following is a collection of tools that might be useful when developing your own plugins.

Plugin API

API for writing plugins.
command description variables targets notes
die exits with error message $@ console returns exit status 1
nb_msg preferred method of verbosity $@ console use instead of echo when appropriate
confirm_action ask user to confirm action none console can be used with $BLOG_INTERACTIVE
chg_suffix changes a file's suffix filename=$1, suffix=$2 file can specify $NB_FILETYPE, $NB_SYND_FILETYPE as suffix
query_db queries database db_query=$1, db_catquery=$2, db_setlimit=$3 db_limit=$4, db_offset=$5 $DB_RESULTS example (retrieves entries 1 through 10): "query_db all nocat limit 10 1"
lookup_entryid lookup entry's id from master database $1, $2 console or redirect example: lookup_entryid 2005-12-14T00_00_00.$NB_DATATYPE "$MASTER_DB_RESULTS"
lookup_monthid lookup month's id from "months" query type $1, $2 console or redirect example: query_db months; lookup_monthid 2005-12 "$MONTH_DB_RESULTS"
set_title2link transforms text for use in links $1 console or redirect none
set_baseurl helps in setting relative links node_var=$1, base_dir=$2 $BASE_URL, $ARCHIVES_PATH should only specify one, of node_var or base_dir, at a time
set_catlink sets link and file for given category $1 $category_file, $category_link category should be of the form, cat_N.$NB_DBTYPE
set_monthlink sets link and file for given month $1 $month_file, $month_link month should be of the form YYYY-MM
set_entryid sets anchor/id for given entry $1 console or redirect entry should be of the form YYYY-MM-DDTHH_MM_SS.$NB_DATATYPE
set_entrylink sets link and file for given entry $1 $entry_dir, $permalink_file, $NB_EntryPermalink entry should be of the form YYYY-MM-DDTHH_MM_SS.$NB_DATATYPE
update_cache compiles list or removes cache entries cache_update=$1, cache_def=$2, CACHEUPDATE_LIST=$3 $CACHE_LIST commonly used to expire cached data
load_template loads template from file TEMPLATE_FILE=$1 $TEMPLATE_DATA never load template data more than once, make_page calls load_template
write_metadata writes metadata to file MTAG=$1, METADATA=$2, META_FILE=$3 $META_FILE example: "write_metadata UPDATED "`date`" $metafile"
read_metadata extracts metadata from (entry) file MTAG=$1, META_FILE=$2 $METADATA see plugin recent_entries.sh for a good example
write_tag create/modify user metedata field WRITE_MTAG=$1, WRITE_MTAGTEXT=$2, WRITEMETATAG_FILE=$3 $WRITEMETATAG_FILE example: write_tag MODTIME "$(date)"
loop_archive loops through archives and executes instructions by years or months looparch_list=$1, looparch_type=$2, looparch_exec=$3 determined by $looparch_exec example: "query_db max; loop_archive "$DB_RESULTS" months make_monthlink"
load_entry loads entry data for templates ENTRY_FILE=$1, ENTRY_DATATYPE=$2, ENTRY_CACHETYPE=$3 $NB_EntryTitle, $NB_EntryBody, ... see plugin atom.sh for a good example
make_page creates weblog page from text file MKPAGE_SRCFILE=$1, MKPAGE_TMPLFILE=$2, MKPAGE_OUTFILE=$3 $MKPAGE_CONTENT, $NB_MetaBody see plugin articles_text.sh for a good example
weblog_page creates weblog page from metafile BLOGPAGE_SRCFILE=$1, BLOGPAGE_TEMPLATE=$2, $BLOGPAGE_OUTFILE=$3 $MKPAGE_CONTENT, $NB_MetaBody see plugin articles_meta.sh for good example

11. Publishing

Setting the Publish Command

The BLOG_PUBLISH_CMD variable allows you to set a command to publish your weblog. This can be as simple as an FTP command to upload files or a more complex set of tasks via a script.

Publishing Remotely

FTP, SSH (scp, sftp, etc.), RSYNC or WebDAV, are all methods that can be used to publish the weblog.

example: automating publishing with ftp and .netrc.

blog.conf:
BLOG_PUBLISH_CMD="ftp example.weblog.com"
 
.netrc:
machine example.weblog.com login foo password
RIGHT!
macdef init
passive on
prompt off
lcd ~/public_html/blog
mput *.*
cd archives
lcd archives
mput *
 

Publishing Locally

If you choose to publish locally, you'll probably want to disable the publish command. To do this you can set BLOG_PUBLISH_CMD to null. e.g. BLOG_PUBLISH_CMD=""

12. Adding Support for Comments

To add support for comments, you can use a PHP script called NanoBlogger Comments [2]. It's simple, features support for accounts, and is easy to install.

Integrating a comment system with your weblog requires editing the appropriate templates. Please see examples in blog.conf and templates.

13. Importing Entries The Hard Way

To import entries the hard way, data first must be converted to the NanoBlogger format.

The Format of an Entry

An entry file name is of the format:

YYYY-MM-DDTHH_MM_SS.txt
        
So a typical entry's file name would look something like this:
2004-06-25T22_24_37.txt
        

The format of an entry is made up 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 is not important.

Example of an entry's format:
TITLE: A New Entry
AUTHOR: foo
DATE: January 30 2004, 12:00 PM
DESC: keywords or a short, one line summary
FORMAT: raw
-----
BODY:
This is my new entry ...
END-----
        

Converting Entries

Before entries can be imported they must be converted to the correct format.

Steps to converting entries:

1. Convert each entry so they each contain the following metadata: TITLE, AUTHOR, DATE, DESC, FORMAT, BODY
2. The BODY metadata must be terminated by "END-----".
3. Rename each entry's file name to it's corresponding date and time.
        

If there's multiple entries it may be a good idea to automate all this with a script.

Updating the Weblog's Data Directory

The imported entries should be copied into the data directory of your weblog.
Update the weblog with the new entries:

nb [-b blog_dir] -u all
        

14. Tips and Tricks

Useful Commands For Editing Sessions

Create a new metafile:
nb [-b blogdir] --makefile somefile.txt
Import the metafile as a new weblog entry:
nb [-b blogdir] --file somefile.txt --add
or export the metafile as a new weblog page:
nb [-b blogdir] --makepage somefile.txt somefile.html
Please note that the editor must support some kind of sub-shell in order to accomplish this or just try suspending your editor from the current shell (assuming there is one).

Writing Metatags on the Fly

Metatags can be written on the fly. For example, text formatting can be set from the command line.

nb [-b blogdir] --tag FORMAT --tag-text "markdown" --makepage somefile.txt somefile.html
    

Set a Default Weblog Directory

By default you have to specify the weblog directory, but by setting BLOG_DIR, you won't have to. Edit nb.conf or $HOME/.nb.conf:

BLOG_DIR="/path/to/weblog"
    

Adding Shell Scripting to Your Templates

It's possible to use command substitution in your templates, using one of the following forms:

        $(command)
or
        `command`
                

Add an Introduction to Your Weblog

Create a text file in your weblog directory called, "intro.txt". Edit the text file the way you like, then add the following to the main template:

$(< "$BLOG_DIR/intro.txt")
        

Integrating Parts of Your Weblog Into a Site

Many parts of the weblog get stored in the parts directory. Say you already have a web site full of your own custom server-side scripts/includes. This is where the "parts/index.html" file comes in. It contains all the current entries, so adding a news/diary/blog section is just a matter of adding the code to include "parts/index.html" into the page. So, now you can have a simple weblog-like page, that's updated whenever index.html changes.

Other clever uses include combining NanoBlogger's static output with some PHP or Perl. For example, suppose you like to have all those nifty links, such as recent entries and archives, using PHP. Set your NB_FILETYPE to PHP and modify the appropriate templates to include the PHP code that extracts the data from the parts directory. One of the main advantages to this is not having to rebuild the entire weblog's archives, just to keep the links current.

Embedding Variables in the Templates

Any characters that are similar to the shell's variable or command substitution characters, will have to be escaped before they will work from the templates.

Example using variables in the PHP code:

<?php
\$VAR = array ();
echo "\\\$VAR=\$VAR";
php?>
     

15. Credits

Thanks to Adrien "ze" Urban, Paul Drain, Pavel Janik, and O.R.Senthil Kumaran for all the contributions and suggestions. Thanks to Bowie J. Poag, author of MicroBlogger [3], for the inspiration of this project.

1. http://nanoblogger.sf.net/downloads/
2. http://nhw.pl/blg/articles/nbcom/
3. http://freshmeat.net/projects/microblogger