Title: A Step-by-step Guide to Your Own Blog
Page: a-step-by-step-guide

We are now ready to explain step-by-step how to create your own blog
using Nukumi2.


## Designing the TopicTree

First of all, you should think about what skeleton tree to use.  For
blogs, `Nukumi2::Entry` uses permalinks at `/archive/YEAR/MONTH/TITLE`
and categories at `/category/CATEGORY`.

So, let's get started.  Create a new directory `myblog` that will
contain your blog:

        mkdir myblog

Inside, create a file `config.rb` with these contents (comments are
interspersed.):

        blog {

First, we set some parameters required in the templates:

          title 'example.org'
          tagline 'cooporate weblog'
          author 'CEO of Example.org'
          mail 'ceo@example.org'
          css '/data/style.css'
          site 'http://example.org/'
          baseuri 'http://example.org/blog'
        
This tag-URI is used for Atom `guid` generation and should be chosen carefully:

          taguri 'tag:ceo@example.org,2004-12-03:example-org-blog'
        
          copyright \
            "Copyright © 2004 Example.org, ceo@example.org\n" +
            "Verbatim copying is permitted as long as this message is preserved."

This a bit cryptic section defines `entries` to hold the blog entries.
You can define as many backends as you want.
        
          register {
            namespace_define!(:backends) {
              example_org { FileBackend.new("entries") }
            }
          }

Now, we get down to the nitty-gritty, the TopicTree.  Each topic has
some attributes, `title` (if given, used in navigation), `view` (the
used view) and `save` (statically render to these flavors).

          topics {
            title 'Front Page'
            view 'Last'
            save ['html', 'rss', 'atom']

Subtopics are created using `topic.SUBTOPIC`:
        
            topic.static {
              title 'Also on this site'
              view 'Subtopic'
              save 'html'
        
              all { view 'Full'; save 'html' }
        
              topic.about { title 'About' }
              topic.projects { title 'Projects'; view 'Direct'}
              topic.contact { title 'Contact' }
            }
            
            topic.category {
              title 'By Category'
              view 'Subtopic'
              save 'html'

There are two kinds of special topics, `any` and `all`.  `any` topics
apply the attributes given to *any* direct subelements while `all`
topics do even more: they apply recursively to *all* the subtopics.
        
              any {
                all {
                  view 'Last'
                  save ['html', 'rss', 'atom']
                }
              }

Now, let's setup some categories:
        
              topic.releases { title 'Software Releases' }
              topic.features { title 'New Features' }
              topic.finances {
                title 'Finances'
                topic.yearly_report {
                  title 'Yearly Reports'
                }
              }
            }
            

This is the default code for archives.

            topic.archive {
              title 'By Date'
              view 'Subtopic'
              save 'html'
        
              any {
                view 'Subtopic'
                save 'html'
        
                all {
                  view 'Last'

Hidden topics won't be shown in the topic overview.  We don't want to show
permalinks here.

                  hidden true
                }
                
                any {
                  view 'Full'
                  save 'html'
        
                  any {
                    view 'Single'
                    hidden true
                    save 'html'
                  }
                }        
              }
            }

Perhaps, you'd also like to add some static pages for contact, a
description of yourself or something.  We will use `/static` for that.

	    topic.static {
	      title 'Also on this site'
	      view 'Subtopic'
	      all {
	        view 'Full'
              }
            }
          }
        }

## Adding entries

You can now start populating your blog with entries.  Since you use
the file backend (there are not others yet), you simply need to create
a file per entry into your `entries` directory.  This file needs to
have a format inspired by
[RFC2822](http://www.ietf.org/rfc/rfc2822.txt) and looks like this:

    Title: Welcome to our new cooporate blog
    Date: Mon, 18 Oct 2004 18:12:15 +0200

    I'm proud to announce that Example.org Ltd. now has an cooporate
    blog.

    Subscribe now, and you won't loose track of our software releases,
    new features of our products and financial reports.

    Happy reading,  
    Your CEO of Example.org

The first paragraph contains the *header*, while the following text is
the *body*.  Every entry should at least have a `Title:` and a
`Date:`, <strong>which contains the *creation* date and *must* not be
changed after publication</strong>.

The body text is by default processed with
[BlueCloth](http://bluecloth.rubyforge.org/) and
[RubyPants](http://kronavita.de/chris/blog/static/projects/rubypants.html),
but this can be customized.  If you wanted to write you entry in
[RedCloth](http://www.whytheluckystiff.net/ruby/redcloth/), for
example, you'd simply need to add:

    Encoding: RedCloth

## Publishing your blog

Now, you need to decide how to publish your blog.  You can either do
this statically or dynamically.  Statically will create files for each
site that can be published with any webserver whereas dynamically
publishing will require you to run [Webrick](http://www.webrick.org/).
(A CGI/FastCGI publisher would be nice to have but is not yet written.)

### Static publishing

To publish static pages, you simply run the `nukumi2` command in your
blogging directory.  It will output all files getting created.  It's
your job now to get them to the appropriate directory or upload
them to a server.

Nukumi2 uses as much relative links as possible.  Sometimes, absolute
links cannot be avoided, though.  Set `baseuri` in the configuration
file to the URI the blog gets published at.


### Dynamic publishing

To publish dynamically, run `nukumi2 -s` inside your blogging
directory.  Now, you can look at your blog by visiting
<http://localhost:2000>.

Well, there you go.  You just set up Nukumi2 in a few easy steps.  The
"difficult" part will come now: [Customizing and Extending
Nukumi2](http://localhost:2000/static/customizing-and-extending-nukumi2.html).