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 and Placeholders |
9. | About Plugins |
10. | Writing Plugins |
11. | Publishing |
12. | Adding Support for Comments |
13. | Importing Entries |
14. | Tips and Tricks |
15. | Credits |
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
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:
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
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 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. edit either nb.conf or $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"
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 "/".
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 to 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".
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.
Changing the File Type
NB_FILETYPE, specifies the file type or rather the suffix for the generated files. The default, of course, 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.
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
Permanently deleting an entry:
nb [-b blog_dir] -d 1Permanently deleting 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
Special Template Characters
IMPORTANT: Escaping these characters prevents them from changing.
characters | description | notes |
---|---|---|
$ | dollar sign | prepend backslash to escape, e.g. "\$" |
` | backquote | 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
templates | description |
---|---|
category_archive.htm | controls look of the categories pages |
entry.htm | controls look of the 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 |
weblog_status.htm | controls look of weblog status |
Placeholders for Entries
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 for Main Index
placeholders | description |
---|---|
${BASE_URL} | relative or absolute link to the weblog's base URL |
$BLOG_MIMETYPE | weblog's mime type |
$BLOG_CHARSET | weblog's character set |
$NB_INDEX | weblog's link to directory's index |
$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_MonthLinks* | links to the monthly archives |
$NB_CategoryLinks* | links to categories |
$NB_MainLinks* | user defined links |
$NB_Entries | all the current entries |
Regular Plugins: plugins
These plugins are initialized first.
Archive Plugins: plugins/archive
These plugins are initialized when the archives are built.
Monthly Plugins: plugins/archive/month
These plugins are initialized for each month. Formally known as monthly plugins.
Entry Plugins: plugins/entry
These plugins are initialized for each entry.
Entry Modify Plugins: plugins/entry/mod
These plugins are initialized for each entry modified, meaning they only get run when an entry's data has been changed. This helps reduce redundancy when generating multiple entries for a page. A good example would be the plugin, moods.sh, which generates graphics for smiley icons. There main use is for altering the data output for an entry. They typically modify the NB_EntryBody, variable. Formally known as entry body plugins.
Page Plugins: plugins/page
These plugins are initialized for each page. They were initially developed to implement a cleaner way for setting dynamic metadata in the templates.
Make Page Plugins: plugins/makepage
These plugins are initialized after each page generated. Formally known as post-format plugins.
Default Plugins
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/month/month_calendar.sh | generates a calendar with links for each active day | none | $NB_MonthlyCalendar | 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_AtomVer, $NB_AtomFile | 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/mod/auto_break.sh | converts blank lines to html paragraph breaks | AUTO_FORMAT | $NB_EntryBody | none |
entry/mod/base_url.sh | helps set relative links | AUTO_FORMAT, %base_url% | $NB_EntryBody | example: <img src="%base_url%images/pic.png" /> |
entry/mod/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 |
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 |
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 | $NB_RSS2File, index-rss.$NB_SYND_FILETYPE | none |
rss.sh | adds rss 1.0 feeds | LIMIT_ITEMS | $NB_RSSFile, index.$NB_SYND_FILETYPE | none |
weblog_links.sh | generates some useful links | none | $NB_MainLinks, $NB_MonthLinks, $NB_CategoryLinks | requires main_links.htm template |
weblog_status.sh | generates some statistics | see notes | $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".
These are a collection of functions that should come in handy when writing a plugin.
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.
Below is a list of functions for plugins.
Plugin API
function | 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 |
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" |
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, META_DATA=$2, META_FILE=$3 | $META_FILE | example: "write_metadata UPDATED "`date`" $metafile" |
read_metadata | extracts metadata from (entry) file | MTAG=$1, META_FILE=$2 | $META_DATA | faster than read_entry, see plugin recent_entries.sh for a good example |
loop_archive | loops through archives and executes intructions 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" |
read_entry | converts entry data for use in templates | ENTRY_FILE=$1 | $NB_EntryTitle, ..., $NB_EntryBody | see plugin atom.sh for a good example |
make_page | generates page from source file and template | MKPAGE_SRCFILE=$1, MKPAGE_TMPLFILE=$2, MKPAGE_OUTFILE=$3 | $MKPAGE_CONTENT, $NB_Entries | see plugin articles.sh for a good example |
Creating Enu_dir] -a
plu" TSo,sh wE_CONTENTt meaniurce fir="0" -s.sh
plugino Display on thOT, $Nclate_c
sestr ut">biiniti
BLOG_CH_MIMETYPE sets the
B chpluleting an entry:
etions for Plu"left">see plu_MIMETYPE<
>
, " or>
"MPL_OU>lugin, for Pluorder
Sitince more pages wiM
aging Entries caali/>
articl_ENjble>ry:
t>see paging Ediv>
da_Entr u" s="eLIMIT_for a grearss2.shtion.
ble>
.he>
PHPion o
BLOG to equal "1", enablmay PHPe
th. Forma advod es tot s.sh foINKS"lefo e maximumy shouentr
TimumgHPe
datializeed in shell>
?php
\$VARks
.hjble>fo FILETimum Numbed align/em> sets the
e>
v
nb [-b b urcigory /h3> writ align="leftleft">$racters
=
nb,o display for eac">descffect all we>
nb [-
n bnd man-3.2.2agraph/ 0000755 0001750 0001750 00000000000 10255370273 014152 5 us. T keKS" keKS"