2.3. Adding a Blog Post or a Page

To write a new blog post, run the following command:

blaze-add

To write a new page, add the --page (or -p) command line option:

blaze-add -p

This opens an external text editor with a pre-formatted header and brief instructions on how to compose a blog entry.

The blog post or page header contains important metadata, such as the title, author, or date of publishing of the entry. For a detailed explanation of all available options, refer to Table 2.1, “A List of Available Header Options”.

Table 2.1. A List of Available Header Options

Option	Type	Description
`title`	Mandatory	Specifies the title of the blog post or page.
`author`	Mandatory	Specifies the author of the blog post or page. The value of the `user.name` (or `user.nickname` if supplied) configuration option is used by default.
`date`	Mandatory	Specifies the date of publishing of the blog post or page, and has to be in the `YYYY-MM-DD` format. The current date is used by default.
`keywords`	Optional	Allows you to specify a comma-separated list of keywords that are specific for the blog post or page.
`tags`	Optional	Allows you to specify a comma-separated list of categories the blog post belongs to. This option is not relevant for pages.
`url`	Optional	Allows you to specify the string to be used in the URL. It must contain alphanumeric characters, hyphens, and underscores only.

Besides ordinary elements defined by the HTML or XHTML standard, BlazeBlogger recognizes several special forms that can be used in the text itself. This includes various placeholders that ensure the cross-references within a particular blog are valid and always point to the expected target. For a complete list of these special forms, refer to Table 2.2, “A List of Special Forms and Placeholders”.

Table 2.2. A List of Special Forms and Placeholders

Form	Description
`<!-- break -->`	Delimits a blog post synopsis.
`%root%`	Is replaced with a relative path to the root directory of the blog.
`%home%`	Is replaced with a relative path to the index page of the blog.
`%page[id]%`	Is replaced with a relative path to a page with the given `id`.
`%post[id]%`	Is replaced with a relative path to a blog post with the given `id`.
`%tag[name]%`	Is replaced with a relative path to a tag with the given `name`.

Refer to Section 3.3, “blaze-add” for a full description of the blaze-add utility and its usage.

Example 2.10. Writing a Blog Post

To open an external editor in order to write a new blog post, type:

public_html]$ blaze-add

The blog post itself may look like the following:

# This and the following lines beginning with '#' are the blog post header.
# Please take your time and replace these options with desired values. Just
# remember that the date has to be in the YYYY-MM-DD form, tags are a comma
# separated list of categories the post (pages ignore these) belong to, and
# the url,  if provided, should consist of alphanumeric characters, hyphens
# and underscores only.  Specifying your own url  is especially recommended
# in case you use non-ASCII characters in your blog post title.
#
#   title:    BlazeBlogger 1.1.1
#   author:   Jaromír Hradílek
#   date:     2010-10-30
#   keywords: release, bug fix
#   tags:     release
#   url:
#
# The header ends here. The rest is the content of your blog post.

<p>
  BlazeBlogger 1.1.1 has been released! This release fixes four bugs that may have caused BlazeBlogger to sort entries in a wrong order, produce invalid RSS feed, or not to run properly when using an older version of Perl.
</p>

<!-- break -->

<h3>Bug Fixes</h3>

<ul>
  <li>
    When the <code>feed.fullposts</code> configuration option was disabled, all HTML/XHTML entities were removed. However, this may have led to an invalid output. With this update, such entities are no longer stripped out, and the RSS feed is now created as expected. (<a href="http://code.google.com/p/blazeblogger/issues/detail?id=18">Issue 18</a>, <a href="http://code.google.com/p/blazeblogger/issues/detail?id=29">29</a>)
  </li>
  <li>
    Due to incorrect use of the <code>cmp</code> operator, both <code>blaze-list</code> and <code>blaze-make</code> utilities may have listed blog posts in a wrong order. With this update, the comparison subroutine has been corrected, so that all entries are now sorted in a correct order. (<a href="http://code.google.com/p/blazeblogger/issues/detail?id=26">Issue 26</a>)
  </li>
  <li>
    <p>When using an older version of Perl, attempting to run the <code>blaze-make</code> utility may have failed with the following error message:</p>
    <pre>blaze-make: Creating `': mkdir : No such file or directory</pre>
    <p>This error no longer occurs, and <code>blaze-make</code> now produces the expected output. (<a href="http://code.google.com/p/blazeblogger/issues/detail?id=30">Issue 30</a>)</p>
  </li>
</ul>