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 basic 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 (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
Creating a New Weblog
To create a new weblog:
cd [nb_dir] ./nb --blogdir [myblog_dir] --addwhere nb_dir is the path that NanoBlogger was installed to and myblog_dir is a nonexistent 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.
For easier invocation, add nb to your $PATH in Bash:
export PATH="$PATH:[nanoblogger_dir]"where nb_dir is the path that NanoBlogger was installed to.
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 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). 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.
Example:
DATE_FORMAT="%m.%d.%Y %H:%M" DATE_LOCALE="$LANG"
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 Language
BLOG_CHARSET sets the character encoding to be used for your weblog.
Example:
BLOG_CHARSET="iso-8859-1"
Setting the Web Address
BLOG_URL should be set as the full URL to your weblog, excluding the index file and any preceding "/".
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"
Enabling Generation of Absolute Links
ABSOLUTE_LINKS enables the generation of absolute links. Defaults to "0", disabled.
Setting the Link for "Main"
MAIN_LINK is used for the navigational link, "main". The default is set to "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".
Toggling the Display of Permanent Links
PERMALINKS toggles the display of an entry's permanent link. The default is to display permanent links.
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.
Plugin Configuration
PLUGINS_DIR, specifies the directory where plugins are located. The default is set to $BASE_DIR/plugins.
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. This configuration is also looked for under the file, $HOME/.nb.conf.
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.
Creating Entries
Adding a new entry:
nb [-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 Entries
Listing current entries:
nb [-b blog_dir] -lListing all entries:
nb [-b blog_dir] -l allListing entries for a category:
nb [-b blog_dir] -c 1 -l
Editing Entries
Editing the last entry created:
nb [-b blog_dir] -e 1Editing an entry from a category:
nb [-b blog_dir] -c 1 -e 1Editing 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 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 Entries
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
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
templates | description |
---|---|
category_archive.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 |
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 permanent link |
$NB_EntryTitle | entry's title |
placeholders | description |
---|---|
$BLOG_CHARSET | weblog's character set |
$MAIN_LINK | weblog's "main" link |
$BLOG_CONTACT | weblog's contact info |
$BLOG_DESCRIPTION | weblog's description |
$BLOG_TITLE | weblog's title |
$BLOG_URL | weblog's URL |
$NB_ArticleLinks | links to articles |
$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 |
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.
General Entry Plugins
Entry plugins are stored in the plugins/entry directory and are loaded for each entry processed.
Entry-body Plugins
Entry-body plugins are stored in the plugins/entry/body directory and are loaded for each entry modified. They typically modify the NB_EntryBody, variable.
Post-format Plugins
Post-format 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. Some plugins may require you to identify it's unique placeholder/destination and manually add it to your templates.
plugins | description | variables | targets | notes |
---|---|---|---|---|
archive/master_index.sh | creates a master index page of the archives | none | $ARCHIVES_DIR/index.html | requires makepage.htm template |
archive/monthly/monthly_cal.sh | generates a calendar with links for each active day | none | $NB_Monthly_Calendar | requires cal |
articles.sh* | generates articles found in the "articles" directory | $NB_ArticleLinks | $ARTICLE_DIR/article_title.$ARTICLE_SUFFIX | requires makepage.htm template, should be last plugin to load |
atom.sh | adds an atom feed | LIMIT_ITEMS | $NB_AtomFile, $NB_AtomAltLink | 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 | see notes | $NB_Blog_Status | requires blog_status.htm template |
calendar.sh | generates a calendar with links for each active day | CAL_CMD, CAL_ARGS | $NB_Calendar | requires cal |
entry/body/auto_break.sh | converts blank lines to html paragraph breaks | AUTO_FORMAT | $NB_EntryBody | none |
entry/category_links.sh | generates category links | none | $NB_EntryCategories | none |
entry/body/moods.sh | converts mood variables into smiley icons | AUTO_FORMAT, MOODS_URL | $NB_EntryBody | copy moods directory to weblog's directory |
fortune.sh | generates random quotes | FORTUNE_FILE | $NB_Fortune | requires fortune |
recent_entries.sh | generates links to recent and old entries | LIST_N, LIST_OFFSET | $NB_Recent_Entries, $NB_Older_Entries | none |
mymood.sh* | adds ability to display your mood | MOODS_URL | $NB_My_Mood | copy moods directory to weblog's directory |
postformat/tidy.sh | validates HTML code | TIDY_ARGS | $NB_Tidy | requires HTML Tidy, overrides $BLOG_CHARSET |
rss.sh | adds rss 1.0 feeds | LIMIT_ITEMS | $NB_RSSFile, $ARCHIVES_DIR/$NB_ArchivePrefix.$NB_SYND_FILETYPE, $NB_RSSAltLink | none |
rss2.sh | adds rss 2.0 feeds | LIMIT_ITEMS | $NB_RSS2File, $ARCHIVES_DIR/$NB_ArchivePrefix-$NB_RSS2File.$NB_SYND_FILETYPE, $NB_RSS2AltLink | none |
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 upload 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=""
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:|----webroot_dir |----cgi-bin (added later) |----cgicomment (added later) |----blog_dir
BLOG_URL_ACTION="http://myblog.com/cgi-bin/cgicomment.pl?article=" ENTRY_ARCHIVES="1"
<a href="$BLOG_URL_ACTION$ARCHIVES_DIR/$permalink_entry">Comments</a>
nb [-b blog_dir] -u all
cd webroot_dir tar xzf CGIComment-XX.tar.gz
BASE_DIR=../cgicomment/ 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 style sheets.
Importing entries from another web-logging system is not entirely impossible. This section hopefully contains the right information to make it possible.
The Format of an Entry
An entry filename is of the format:
YYYY-MM-DDTHH_MM_SS.htmSo a typical entry's filename would look something like this:
2004-06-25T22_24_37.htm
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 ----- BODY: This is my new entry ... -----
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, 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.
Updating the Weblog's Data Directory
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
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 and set BLOG_DIR to your weblog directory.
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`This is mostly useful for small and simple dynamic changes you wish to make to the content generated from the templates.
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:
$(< "$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.
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/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.
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://nanoblogger.sf.net/downloads/
2. http://freshmeat.net/projects/cgicomment/
3. http://freshmeat.net/projects/microblogger