• Composed of less than 600 lines of code!
• Supports any text formatting system imaginable!
• Automatic table of contents for blog entries.
• Automatic syntax coloring for source code.
• User-friendly output for text-only web browsers.
• Foreign language support for 16 languages.

• Categorization by tags (also known as folksonomy).
• Automatic archives by date, month, year, etc.
• Automatic RSS feeds for blog entires, tags, etc.
• Automated blog import from any RSS feed.

Copyright 2006 Suraj N. Kurapati <SNK at GNA dot ORG>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

• All copies and substantial portions of the Software (the "Derivatives") and their corresponding machine-readable source code (the "Code") must include the above copyright notice and this permission notice.

• Upon distribution, the Derivatives must be accompanied by either the Code or—provided that the Code is obtainable for no more than the cost of distribution plus a nominal fee—information on how to obtain the Code.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Although dynamic blog engines are popular nowadays, static blog engines like Rassmalog are still relevant. The following sections attempt to explain why.

The basic unit of content in Rassmalog is the blog entry. Entries are collected into sections. Pages are collected into chapters.

As you can see, there is a hierarchical relationship here:

• Chapter
  • Section
    • Entry

• a chapter shows all available tags
• a section shows all entries that have a particular tag
• an entry just shows its content

Furthermore, a listing is just a list of blog entries.

Your system needs the following software to run Rassmalog.

If your system has RubyGems, then you can install Rake, RedCloth, and CodeRay by running the following command:

gem install rake RedCloth coderay

1. Download the newest release package from the download area.
2. Extract the release package anywhere you want on your system.
3. Go inside the extracted directory and run the following command:

   rake regen

If the installation was successful, then you will see output like this:

(in /home/sun/tmp/rassmalog)
        copy  output/styles/print.css
        copy  output/styles/screen.css
        copy  output/images/feed-icon-14x14.png
       Entry  output/example-paths.html
       Entry  output/2006-12-14-formatting-with-textile.html
       Entry  output/2006-12-20-automatic-image-resizing-for-thumbnails.html
       Entry  output/2007-09-25-dynamic-web-based-comments.html
       Entry  output/2007-03-25-automatic-tagging-of-directory-names.html
       Entry  output/blog-entry-file-format.html
       Entry  output/2007-09-25-an-entry-from-the-entries-directory.html
       Entry  output/2007-11-02-version-8-0-1.html
       Entry  output/2006-12-14-version-2-0-0.html
       Entry  output/2007-12-09-version-9-0-1.html
       Entry  output/2007-10-23-version-7-1-0.html
       Entry  output/2007-09-25-version-6-0-0.html
       Entry  output/2007-01-22-version-2-3-0.html
       Entry  output/2007-01-27-version-2-4-0.html
       Entry  output/2006-12-18-version-2-1-1.html
       Entry  output/2007-04-16-version-4-0-0.html
       Entry  output/2008-06-08-version-11-1-0.html
       Entry  output/2007-11-12-version-8-0-2.html
       Entry  output/2007-05-25-version-5-0-0.html
       Entry  output/2008-01-11-version-10-0-0.html
       Entry  output/2006-12-11-version-1-0-0.html
       Entry  output/2007-10-05-version-7-0-1.html
       Entry  output/2007-03-25-version-3-2-0.html
       Entry  output/2007-03-04-version-3-0-0.html
       Entry  output/2007-11-01-version-8-0-0.html
       Entry  output/2007-05-05-version-4-1-0.html
       Entry  output/2007-10-24-version-7-1-1.html
       Entry  output/2008-05-02-version-11-0-1.html
       Entry  output/2006-12-15-version-2-1-0.html
       Entry  output/2007-03-05-version-3-1-0.html
       Entry  output/2008-01-21-version-10-1-0.html
       Entry  output/2007-01-13-version-2-2-0.html
       Entry  output/2007-10-04-version-7-0-0.html
       Entry  output/2007-07-04-version-5-1-0.html
       Entry  output/2007-12-05-version-9-0-0.html
       Entry  output/2008-05-18-version-11-0-2.html
       Entry  output/2008-05-01-version-11-0-0.html
       Entry  output/2007-06-05-version-5-0-1.html
     Section  output/tags-examples.html
     Section  output/tags-history.html
     Section  output/tags-reference.html
     Section  output/tags-tricks.html
     Chapter  output/tags.html
     Section  output/archives-december-2006.html
     Section  output/archives-january-2007.html
     Section  output/archives-march-2007.html
     Section  output/archives-april-2007.html
     Section  output/archives-may-2007.html
     Section  output/archives-june-2007.html
     Section  output/archives-july-2007.html
     Section  output/archives-september-2007.html
     Section  output/archives-october-2007.html
     Section  output/archives-november-2007.html
     Section  output/archives-december-2007.html
     Section  output/archives-january-2008.html
     Section  output/archives-may-2008.html
     Section  output/archives-june-2008.html
     Chapter  output/archives.html
     Listing  output/all-entries.html
     Listing  output/new-entries.html
  front_page  output/new-entries.html
       Entry  output/search.html
        feed  output/feed.xml
        feed  output/tricks.xml

Now that Rassmalog is installed on your system, let us examine its installation directory. Inside, you will see (among other things) the following items:

• rassmalog.rb – the core of Rassmalog.

• doc/ – documentation for Rassmalog users
  • doc/guide.erb – source code of this user guide

• config/ – directory that contains all configuration files.
  • config/blog.yaml – the primary configuration file for your blog.
  • config/feed.erb – template for generating RSS feeds for the blog.
  • config/html.erb – template for generating a complete HTML web page.
  • config/chapter.erb – template for generating HTML for lists of tags and archives.
  • config/section.erb – template for generating HTML for individual tags and archives.
  • config/listing.erb – template for generating the recent/all lists of blog entries.
  • config/entry.erb – template for generating HTML for a blog entry.
  • config/format.rb – defines how text is transformed into HTML.
  • config/lang/ – directory that contains translations of English text used in the core of Rassmalog. These translations do not include English text used in the templates (config/*.erb) because those are already separate from the core of Rassmalog.

• config/lang/de.yaml (German)

• config/lang/el.yaml (Greek; Modern)

• config/lang/es.yaml (Spanish; Castilian)

• config/lang/fr.yaml (French)

• config/lang/id.yaml (Indonesian)

• config/lang/it.yaml (Italian)

• config/lang/ja.yaml (Japanese)

• config/lang/ko.yaml (Korean)

• config/lang/nl.yaml (Dutch; Flemish)

• config/lang/no.yaml (Norwegian)

• config/lang/pt.yaml (Portuguese)

• config/lang/ru.yaml (Russian)

• config/lang/sv.yaml (Swedish)

• config/lang/te.yaml (Telugu)

• config/lang/zh-TW.yaml (Chinese (Taiwan))

• config/lang/zh.yaml (Chinese)

• output/ – directory that contains your generated blog.

• input/ – directory that contains (1) source files for blog entries and (2) additional resources, such as images and stylesheets, that are used by your blog. Everything inside this directory, except source files for blog entries, is automatically copied into the output/ directory (relative paths are preserved) when your blog is generated.

  A blog entry source file’s name must end with a .yaml extension. By default, a source file’s corresponding output file has (1) the same name and relative path as the source file but (2) ends with a .html extension.

  For example, the input/foo/bar/moz.yaml source file’s corresponding output file is output/foo/bar/moz.html. You can override this default behavior by adding the output_file parameter to your blog entry.

  • input/styles/screen.css – the default CSS stylesheet provided with Rassmalog.
  • input/styles/print.css – the default CSS stylesheet provided with Rassmalog.
  • input/rassmalog/entry.yaml – reference of the blog entry file format.

• entries/ – directory that contains blog entry source files whose output files are automatically calculated by Rassmalog.

  A blog entry source file’s name must end with a .yaml extension. By default, all source files in this directory will have a corresponding output file with a name in the form: “date-name.html”.

  For example, the entries/foo/bar/moz.yaml source file, which was written on 19 July 2006 and has a name of “hello world”, will have a corresponding output file at output/2006-07-19-hello-world.html. You can override this default behavior by adding the output_file parameter to your blog entry.

  As you can see, unlike the blog entries in the input/ directory, blog entries in the entries/ directory do not have to worry about their original file name influencing the output file name. As a result, you can organize your blog entry files however you want.

  For example, I like to put all blog entry files related to Ruby programming within the entries/code/ruby/ subdirectory. The names of these subdirectories do not have any special meaning to Rassmalog, so you can name them however you like.

"entries/{today's date}+{serial number}.yaml"

rake new

rake new name='hello world' date='2008 march 17' tags='foo,bar' text='hey!'

rake new tags='foo,bar,hello world'

rake new file='hello_world.yaml'

Rassmalog uses the RubyGems rational versioning policy to number its releases. This major.minor.patch numbering policy is summarized as follows.

The following subsections describe the configuration parameters available for use in the config/blog.yaml file.

email:   # nothing here!

email: your@email.here
email: your+blog@email.here
email: your+comments@email.here

url: http://your_host.com/~you/path/to/your/blog/
url: http://you.your_host.com/path/to/your/blog/

<%= whole %> is a path to the output/ directory which must be uploaded.

<%= parts %> is a sequence of quoted paths to files that must be uploaded.
             For example, the result of this directive is something like:
             "output/foo" "output/bar" "output/baz qux moz"

uploader: scp -prC <%= parts %> user@host:public_html
uploader: rsync -e ssh -auvz <%= whole %>/ user@host:public_html
uploader: lftp sftp://user@host -e 'mirror -Ra --ignore-time <%= whole %>/ public_html; exit'

uploader: lftp host -u 'user,password' -e 'mirror -Ra --ignore-time <%= whole %>/ public_html; exit'

encoding: utf-8       # Unicode (for all languages)
encoding: x-sjis      # Shift JIS (for Japanese only)
encoding: x-iscii-te  # Telugu ISCII (for Telugu only)

http://en.wikipedia.org/wiki/List_of_ISO_639-2_codes

http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Current_codes

language: en    # English
language: en-us # English (United States)
language: en-gb # English (Great Britain)

$ irb -r locale
>> Time.now
=> Tue Oct 23 13:12:20 -0700 2007

# in German:
>> Locale.setlocale(Locale::LC_TIME, "de_DE"); Time.now
=> Di Okt 23 13:12:32 -0700 2007

# in Spanish:
>> Locale.setlocale(Locale::LC_TIME, "es_ES"); Time.now
=> mar oct 23 13:15:19 -0700 2007

# in Italian:
>> Locale.setlocale(Locale::LC_TIME, "it_IT"); Time.now
=> mar ott 23 13:15:27 -0700 2007

locale:   # nothing here!

locale -a

front_page:   # nothing here!

new_entries:   # nothing here!

summarize_entries: false

archive_frequency: %Y

archive_frequency: %Y-%m

archive_frequency: %Y-%m-%d

archive_frequency: put your own value here

http://www.rubycentral.com/pickaxe/ref_c_time.html#Time.strftime

The core of Rassmalog is easily localized (L10N / I18N / M17N) through translation files, which consist of simple key-value pairs. For instance, the translation file for Spanish appears like this:

# es (Spanish; Castilian)
All entries: Todas las entradas
Archives: Archivos
Authored by %s.: Sido autor por %s.
Generated by %s.: Generado por %s.
Navigation: Navegación
New entries: Nuevas entradas
Newer: Más nuevo
Next: Después
Older: Más viejo
Previous: Anterior
Read more...: Lea más...
Search: Búsqueda
Subscribe: Suscriba
Tagged as %s.: Marcado con etiqueta como %s.
Tags: Etiquetas
Written on %s.: Escrito en %s.
You are now being redirected to %s.: Le ahora están volviendo a dirigir a %s.
You may {send comments by e-mail}.: Usted puede {envíe los comentarios por E-mail}.

Here, English phrases are written on the left and their corresponding Spanish phrases are written on the right.

language: foobar

To use another text formatting system, simply replace the String.to_html method, which is defined in the config/format.rb file, to make use of your desired text formatting scheme.

For example, if you replace the entire config/format.rb file with the following code, then all entries will appear within red boxes in the output.

class String
  def to_html
    '<p style="border: thin solid red">' + self + '</p>'
  end
end

In this manner, you can make Rassmalog use any formatting system you wish!

Suppose you wanted to disable the generation of the RSS feed for your blog. In order to do this,

1. Open the Rakefile in your text editor.
2. You should now see a line of code similar to this:
   task :gen => [:copy, :entry, :entry_meta, :entry_list, :feed]
3. Remove the :feed element from the line of code.

In this manner, you can disable other parts of the blog generation process. Furthermore, you can edit the source code in the “output generation stage” section to suit your needs.

The search page is just a blog entry; there is nothing special about it.

1. Delete the input/search.yaml file.
2. Remove the HTML search form in the config/html.erb template.
3. Regenerate your blog.

• think of and manage unique file names every time
• supply the current date and time
• remember the entire syntax of a blog entry file
• remember the names of all tags you have used thus far

To use this plugin, run the following command:

rake new

After it executes, the command will report the name of the file it created. You can then edit the created file using your favorite text editor and fill in all the juicy details.

To generate your blog, run the following command:

rake

Or alternatively, you can run:

rake gen

To regenerate your blog from scratch (delete all existing output and generate everything again), run the following command:

rake regen

To remove all output files that were generated by Rassmalog, run the following command:

rake clean

To remove everything inside the output/ directory, run the following command:

rake clobber

To upload your blog to your website, run the following command:

rake upload

To continuously preview a blog entry as you write it, run the following command:

rake preview

Now, whenever you save your blog entry file, its HTML page will be generated for preview in your web browser.

The import task allows you to import blog entries from an RSS feed, which must be provided on the standard input stream.

For example, if you have an RSS feed file named feed.xml then you would import it into Rassmalog like this:

rake import < feed.xml

1. Open the Rakefile in your text editor.
2. You should now see a some code similar to this:

   feed 'feed.xml', NEW_ENTRIES, BLOG.name, BLOG.info
   

   This code invokes the feed method to create an RSS feed.
3. Add your own invocation of the feed method to the bottom of the file (see the API documentation in Section 6.1. API documentation for help).

# gather the desired entries
entries = TAGS['foo'] + TAGS['bar'] + TAGS['moz']

# remove duplicate entries
entries.uniq!

# create the feed
feed 'example.xml', entries

The following subsections describe the parameters you can use in a blog entry file. For an example of usage, see the input/rassmalog/entry.yaml file.

date: Thu, 01 Jan 1970 08:00:00 GMT
date: 1970-01-01 8:00am
date: 1/1/1970 8:00am
date: jan 1st 1970 16:00 -08:00
date: 1 january 1970
date: Wed Dec 13 21:31:04 PST 2006

date: Thursday, 01 January 1970 03:15:00 PM

date: Donnerstag, 01 Januar 1970 15:15:00

ri Time.parse

http://www.ruby-doc.org/core/classes/Time.html#M000297

The text of a blog entry is treated as an eRuby template. Thus, you can use eRuby directives (which appear within <% and %> tags) in the text of your blog entries.

For example, putting the following text in a blog entry:

<% 3.times do %>

* Hello World!
<% end %>

Produces the following result:

• Hello World!
• Hello World!
• Hello World!

<%= File.read('path-to-your-file') %>

<%= h File.read('path-to-your-file') %>

Rassmalog adjusts all relative URLs in the final HTML output to be relative to the output/ directory. This is done to give all blog entries (regardless of how deep they are inside the input/ directory) a common way to access files. As a result, some extra work is necessary to access files that are relative to a blog entry itself.

For example, suppose that (1) we have the following directory structure and that (2) the input/food/fruit/banana.yaml blog entry contains the ../nuts/walnut.html relative URL.

• input/
  • food/
    • fruit/
      • banana.yaml
    • nuts/
      • walnut.yaml

• output/
  • food/
    • fruit/
      • banana.html
    • nuts/
      • walnut.html

Rassmalog will change ../nuts/walnut.html into ../../../nuts/walnut.html by adding a ../../ prefix. As a result, the changed URL is now referring to a nonexistent nuts/walnut.html file that resides one level above the output/ directory!

One solution is to manually rewrite to rewrite the original URL to be relative to the output/ directory: ../nuts/walnut.html becomes food/nuts/walnut.html.

Another solution is to use an eRuby directive to add the blog entry source file’s parent directory’s path to the relative URL: ../nuts/walnut.html becomes

<%= File.dirname(@entry.output_url) %>/../nuts/walnut.html

A table of contents is automatically generated from headings (<h1> through <h6> for HTML and h1. through h6. for Textile) found in the text of a blog entry.

Headings are numbered in the style of LaTeX; these numbers contain a hyperlink back to the table of contents for easier navigation.

If you want to disable the table of contents for a particular blog entry, then see the generate_toc parameter in the list of parameters above.

If you want to disable the table of contents globally, for all blog entries, then see the generate_toc parameter in your config/blog.yaml configuration file.

Syntax coloring is automatically added to source code found inside the <code> and </code> HTML tags. Note that in Textile, any text enclosed within a pair of at-signs (@ and @) is also considered to be source code.

• Ruby
• C
• Delphi
• HTML
• RHTML (Rails)
• Nitro-XHTML

This feature can be disabled or changed by editing the config/format.rb file accordingly.

# Ruby ###########################
def hello
  puts "Hello world!"
end


/* C ****************************/
#include <stdio.h>
int main(int argc, char **argv) {
  printf("Hello world!\n");
  return 0;
}


<!-- HTML ----------------------->
<html>
  <body>
    Hello world!
  <body>
</html>

# Ruby ###########################
def hello
  puts "Hello world!"
end


/* C ****************************/
#include <stdio.h>
int main(int argc, char **argv) {
  printf("Hello world!\n");
  return 0;
}


<!-- HTML ----------------------->
<html>
  <body>
    Hello world!
  <body>
</html>

# Ruby ###########################
def hello
  puts "Hello world!"
end


/* C ****************************/
#include <stdio.h>
int main(int argc, char **argv) {
  printf("Hello world!\n");
  return 0;
}


<!-- HTML ----------------------->
<html>
  <body>
    Hello world!
  <body>
</html>

life =
true or false

Sometimes you just need to protect some text from being mangled by the text-to-HTML conversion process (which is governed by config/format.rb). In such cases, you can wrap the text you want to proctect within <noformat> and </noformat> tags.

Note that this is a feature of the default config/format.rb file provided with Rassmalog. If you defined your own text-to-HTML conversion scheme, then this feature might not work.