Table of Contents
Synopsis
nb [-b blogdir] [options]
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.bash, cat, cp, cut, dirname, date, expr, grep, mkdir, mv, read, rm, sed, sort, touch, trap
To create a new blog invoke:nb --blogdir myblog_dir --addwhere "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.
nb --blogdir myblog_dir --configureThis 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.
* = used by plugin
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
* = generated 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
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 EntryEntries 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.
AUTHOR: foo
DATE: January 30 2004, 12:00 PM
DESC: the description of this entry
-----
BODY:
This is my new entry ...
-----
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.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.
To disable a plugin, rename the plugin's extension from ".sh" to ".off".
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
`cat "$BLOG_DIR"/intro.txt`Note the use of left single quotes, they're important. Also, note that no processing is being done this way, you have to add your own HTML.
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 [2] and was easy to integrate into my blog. The cool thing about CGIComment is it's ability to append comments to any HTML document. Here are the steps to enable comments:When you have comments working you can download my modified set of CGIComment templates[1] that have been designed to integrate with NanoBlogger's default stylesheets.