NAME
blazeintro - an introduction to BlazeBlogger
SYNOPSIS
$ blaze-init
$ blaze-add
$ blaze-make
DESCRIPTION
This document tries to provide a brief introduction on how to create,
configure, add new content to, and generate a static content from the
BlazeBlogger repository.
Although each command described below is actually an autonomous
utility, on most Unix systems, BlazeBlogger should be shipped with a
command wrapper, making it possible to use "blaze-command" and more
usual "blaze command" interchangeably. In this text, however, we will
strictly use the first form, as it is the most portable variant.
Creating a New Blog
To create a new blog, you have to create a repository first. Similarly
to Git, BlazeBlogger repository is just a (usually hidden) directory
named ".blaze", where all the blog data and configuration are stored
and from which the static content, i.e. the HTML pages, is generated.
In most cases, it is placed in the same directory as the generated
content.
Assuming you are already in the directory where the blog repository is
to be placed, you can create a new one typing:
$ blaze-init
If nothing goes wrong, you should get a response similar to this:
Created a BlazeBlogger repository in .blaze.
As the message suggests, you can use the same command any time later to
return the repository to a consistent state while leaving the rest of
your data (e.g. configuration, blog posts and pages) intact.
Optionally, you can force the utility to restore the configuration,
theme, style and language files to their initial state by adding the
following option:
$ blaze-init --force
Configuring the Blog
Although the defaults try to be reasonable enough and ready for an
immediate use, there are few options you might at least want to know
about.
The first thing probably to be changed is an external text editor you
will be using for writing your posts. Unless this option is set,
BlazeBlogger tries to use system wide settings by looking for EDITOR
environment variable, and if neither of these options is supplied, "vi"
is used as a considerably reasonable option. To change it to, lets say,
"pico", type:
$ blaze-config core.editor pico
Another things you might want to change are the heading and subheading
of your blog, and the default user name; for example:
$ blaze-config blog.title My Blog
$ blaze-config blog.subtitle yet another blog
$ blaze-config user.name Your Name
Furthermore, if you intend to generate RSS feed, you have to specify
the base URL:
$ blaze-config blog.url http://blog.example.com/
Finally, if you prefer coloured output in your terminal window, you can
enable it individually for each utility that supports it:
$ blaze-config color.list true
$ blaze-config color.log true
For the complete list of available options, see blaze-config(1) manual
page. To see the current setting, simply type the option name without
the value:
$ blaze-config user.name
You can also edit all options at once opening the configuration file in
the external text editor:
$ blaze-config --edit
Managing the Blog Posts
To add a new blog post to the repository, type:
$ blaze-add
This will open the external editor with a pre-formatted header and
empty body for you to write. Although the most of the header lines are
devoted to the exhaustive explanation of what exactly you should and
should not fill in, let’s take a closer look at the five header options
just to make sure everything is perfectly clear:
title
The title of your post; you do not want to omit that one, do you?
author
The post author. The user name specified in the configuration is
used by default, but you are free to change it to whatever name you
wish.
date
Date of the publishing of the post. It has to be in the YYYY-MM-DD
form (i.e. 17 July 2009 would look like 2009-07-17 etc.) and it has
to be filled. The default option is current date.
tags
Comma separated list of categories the post belongs to. The exact
number of attached tags is not limited as long as they are all
listed on the same line. Since tags are completely optional, you
can safely leave this option empty, or fill it any time later.
url The use of term ‘URL’ in this context is quite vague and simply
means the part of the URL representing the particular post. As it
is derived from the post title, you usually do not have to bother
with it at all. There are however two cases when it might prove
useful: (1) when your title contains special characters (typically
foreign diacritical marks) that BlazeBlogger strips away and you
still want your URL look pretty, or (2) in case you want your URL
different from the title, for example because of the title length.
Remember that the URL should consist of alphanumeric characters,
hyphens and underscores only.
Keeping that in mind, your first post might look somehow like the one
below:
# This and following lines beginning with `#' are the post header.
# Please take your time and replace these options with desired val-
# ues. Just remember that the date has to be in an YYYY-MM-DD form,
# tags are a comma separated list of categories the post (pages ig-
# nore these) belong to, and the url, if provided, should consist of
# alphanumeric characters, hyphens and underscores only. Specifying
# your own url is especially recommended when you use non-ASCII cha-
# racters in your post title.
#
# title: The Hobbit, or There and Back Again
# author: David
# date: 2009-07-17
# tags: childrens literature, fantasy
# url: the-hobbit
#
# The header ends here. The rest is the content of your post.
<p>“In a hole in the ground there lived a hobbit.”
— these are the words that introduces us to the incredible
world of nowadays classic Tolkien's novel. But what is so
fascinating about it that generation after generation keep returning
to its charms?</p>
<!-- break -->
<p><em>The Hobbit</em> is a story about Bilbo Baggins, a hobbit ...
Note that you can use "<!-- break -->" to mark the end of the part to
be displayed on index page. You can also use a special placeholder,
"%root%", as a relative path to the base URL (directory where the blog
is placed) in your links and images. For example, to link the RSS feed
from your blog post, write:
<a href="%root%index.rss">RSS Feed</a>
When you are done, save your changes and close the editor. You should
get a confirmation message with the ID of the new post.
If you prefer to write your posts in advance (e.g. work with concepts),
you can also add any number of existing files without opening the text
editor like this:
$ blaze-add file1 file2 file3
To edit the existing post, e.g. with ID number 3, type:
$ blaze-edit 3
To completely remove the post with ID 3 from the repository, use the
following command:
$ blaze-remove 3
Do not forget that the utility has no conscience and remorselessly
deletes anything you tell it to, with no way to take it back (unless
you have backup, of course). To prevent the accidental loss of
potentially valuable data, you might want to consider running it in an
interactive mode using the "--interactive" (or shorter "-i") option and
thus having to confirm every deletion.
Managing the Pages
Pages are the right place for all those information that have to be
immediately accessible from every page on your website (typically the
About, Contact, Downloads or Screenshots sections). They are usually
kept in a relatively small number and generally do not tend to vary
much. In the default theme, they are being listed in the horizontal
menu below the blog title.
Similarly to blog posts, you can manage pages using the same commands
with additional "--page" (or "-p" for short) option. Adding new page
would therefore look like this:
$ blaze-add --page
Unlike posts, pages do not respect tags, nor do they display their
author and the date of publishing. The latter is however still taken in
account in the sorting process, making it possible to alter the order
of pages in the menu according to your taste.
To edit existing page with ID 3, use:
$ blaze-edit --page 3
Finally, to remove pages with ID 2, type:
$ blaze-remove --page 2
Browsing the Blog Repository
To display all blog posts in the repository, e.g. to look up an ID of
the particular post, use following command:
$ blaze-list
You can also narrow the results by providing the additional
specifications like date, tag or author. For example, to find all posts
from 19 December 2008 written by David, type:
$ blaze-list --author David --year 2008 --month 12 --day 19
To browse pages instead of blog posts, simply add the "--pages" option:
$ blaze-list --pages
Generating the Static Content
To generate the static content from your repository in the current
working directory, with all posts, pages, monthly and yearly archives,
tags and RSS feed included, type:
$ blaze-make
or if you wish to see a list of files as they are created:
$ blaze-make --verbose
You can now check the appearance of your web presentation in the
browser and/or copy the files to the hosting. Note that you can force
the full paths creation to make it easier to browse the off-line
content:
$ blaze-make --full-paths
Furthermore, if the public web directory is located on the same server,
you can create the content directly in that location by specifying the
destination directory:
$ blaze-make --destdir ~/public_html
For the complete list of all command line options, see blaze-make(1)
manual page.
Observing the Repository History
Since every significant change in the repository (i.e. its
initialization and recovery, as well as post/page addition, editing and
removal) is automatically logged along with the exact time of when it
happened, you can view the whole history typing:
$ blaze-log
or if you want to save space:
$ blaze-log --short
Changing the Blog Theme
Changing the theme of your blog is rather straightforward. First,
extract the content of the theme package to the directory where the
static content is being generated; for example, to install the theme
called VectorLover:
$ tar xfz vectorlover-1.0.tar.gz
Open the template file, in this case "vectorlover.html", in your
favourite text editor and replace the sidebar sections like ‘About’ or
‘Links’ with appropriate information. Then place both template file and
the corresponding stylesheet to the ".blaze/theme/" and ".blaze/style/"
directories respectively:
$ mv vectorlover.html .blaze/theme/
$ mv vectorlover.css .blaze/style/
Finally, change the configuration to use this theme:
$ blaze-config blog.theme vectorlover.html
$ blaze-config blog.style vectorlover.css
Run blaze-make(1) to re-create the static content with the new outfit.
For more information on how to modify existing theme or create a new
one from scratch, see blazetheme(7) manual page.
Changing the Blog Localization
To change the blog language to, let’s say, Czech, copy the file "cs_CZ"
to the ".blaze/lang/" directory and change the appropriate
configuration option:
$ blaze-config blog.lang cs_CZ
Next time you invoke blaze-make(1), all generated strings should be
properly translated.
FILES
.blaze/config
BlazeBlogger configuration file.
.blaze/log
BlazeBlogger repository log file.
.blaze/theme/
BlazeBlogger themes directory.
.blaze/style/
BlazeBlogger stylesheets directory.
.blaze/lang/
BlazeBlogger language files directory.
SEE ALSO
blaze-init(1), blaze-config(1), blaze-add(1), blaze-edit(1), blaze-
remove(1), blaze-list(1), blaze-make(1), blaze-log(1).
AUTHOR
Written by Jaromir Hradilek <jhradilek@gmail.com>
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included as a file called FDL in the main
directory of the BlazeBlogger source package.