Table of Contents
Synopsis
nb [-b blog_dir] [options]
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
Three easy steps to upgrading. Any customizations made will have to be copied over manually, such as modified templates.1. create a new weblog directory using nanoblogger (skip the configuration): nb [-b blog_dir] -a 2. copy the old archives (data) directory over to the new weblog directory: cp -r [old_blog_dir]/archives [newblog_dir] 3. edit the new blog.conf to your likings and rebuild the weblog: nb [-b blog_dir] -u all
bash, cat, cp, cut, dirname, date, expr, grep, mkdir, mv, read, rm, sed, sort, touch, trap
To create a new weblog 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 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.To set a default weblog directory:
1. create and edit .nb.conf in your $HOME directory: vi $HOME/.nb.conf 2. set BLOG_DIR to your weblog directory: BLOG_DIR="$HOME/public_html/[myblog_dir]"
nb --blogdir [myblog_dir] --configure -u allThis opens blog.conf from the weblog directory for editing and updates all of the weblog.
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 weblog. Typically, you would set this to a remote address such as: "http://myblogurl.com". Replacing myblogurl.com with the actual address to your weblog.
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 weblogs. The global configuration file is read first meaning that settings in the weblog's configuration may override settings in nb.conf. Typically one would set BLOG_DIR here as a default weblog directory to use. This configuration is also looked for under the file, $HOME/.nb.conf.
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.Creating Entries
Adding a new entry:Listing Entriesnb [-b blog_dir] -aAdding a new entry to a category:nb [-b blog_dir] -c 1 -aSetting title and author for new entry:nb [-b blog_dir] -t "New Entry" -n [entry_author] -aSetting title, author, and body for new entry:nb [-b blog_dir] -t "New Entry" -n [entry_author] -M "This is my message." -a
Listing current entries:Editing Entriesnb [-b blog_dir] -lListing all entries:nb [-b blog_dir] -l allListing entries for a category:nb [-b blog_dir] -c 1 -l
Editing the last entry created:Moving Entriesnb [-b blog_dir] -e 1Editing an entry from a category:nb [-b blog_dir] -c 1 -e 1
Moving an entry to a category:Deleting Entriesnb [-b blog_dir] -c 1 -m 1Moving an entry to multiple categories:nb [-b blog_dir] -c 1,2,3 -m 1Moving multiple entries to a category:nb [-b blog_dir] -c 1 -m 1,2,3
Deleting an entry:nb [-b blog_dir] -d 1Deleting multiple entries:nb [-b blog_dir] -d 1,2,3Deleting an entry from a category:nb [-b blog_dir] -c 1 -d 1
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 -aSetting the title for a new category:nb [-b blog_dir] -t "New Category" -c new -aListing available categories:nb [-b blog_dir] -l catEditing a category's title:nb [-b blog_dir] -c 1 -t "News" -e catDeleting a category:nb [-b blog_dir] -c 1 -d cat
* = used by plugin
The weblog's appearance is controlled by the following templates: templates description category.htm controls look of the categories pages entry.htm controls look of your weblog entries 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 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
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 weblog by creating a "plugins" directory under a weblog'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 CAL_ARGS $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 weblog'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 weblog's directory postformat/tidy.sh validates HTML code TIDY_ARGS $NB_Tidy requires HTML Tidy rss.sh adds rss feeds LIMIT_ITEMS $BLOG_URL/index.$NB_SYND_FILETYPE, $BLOG_URL/$ARCHIVES/cat_n.$NB_SYND_FILETYPE none
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
Assuming your service provider supports it, you can use FTP to upload the weblog. Be sure to use recursive mode when uploading your weblog directory:Publishing Locally
ftp myblog.com, put -r [blog_dir]If you're not limited to FTP, you might want to consider SSH (scp, sftp, etc.), rsync or WebDAV.
You can run a private web server or Change the weblog's address to a more direct "file:///" address, so you can view it locally using almost any web browser. 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=""
To add support for comments, you can use a cgi script called CGIComment [2]. CGIComment is a nice solution because it integrates the comments directly into the article.
Here are the steps to enable comments using CGIComment:BLOG_URL_ACTION="http://myblog.com/cgi-bin/cgicomment.pl?article=" ENTRY_ARCHIVES="1"
<a href="$BLOG_URL_ACTION$PERMALINKS_DIR/$permalink_entry">Comments</a>
nb [-b blog_dir] -u all
cd /var/www mv /tmp/CGIComment-XX.tar.gz ./ tar xzf CGIComment-XX.tar.gz
BASE_DIR="[cgicomment_dir] ARTICLEDIR="[blog_dir]"
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.
Importing entries from another weblogging system is not entirely impossible. This section hopefully contains the right information to make it possible.
The Format of an EntryAn entry filename is of the format:Converting EntriesYYYY-MM-DDTHH_MM_SS.htmSo a typical entry's filename would look something like this:2004-06-25T22_24_37.htmThe 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 ----- BODY: This is my new entry ... -----
Before entries can be imported they must be converted to the correct format.
Steps to converting entries:Updating the Weblog's Data Directory1. Convert each entry so they each contain the following metadata: TITLE, AUTHOR, DATE, DESC, BODY 2. Rename each entry's filename 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.
The imported entries should be copied into the archives (data) directory of your weblog.
Update the weblog with the new entries:nb [-b blog_dir] -u all
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 and set BLOG_DIR to your weblog directory.Add an introduction to your Weblog
Create a text file in your weblog directory called, "intro.txt". Edit the text file to say what you want, then add the following to the main template:Integrating Parts of your Weblog into a Site
`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.
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/news.htm" 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/news.htm" into the page. So, now you can have a simple weblog-like page, that's updated whenever news.htm changes.