org-ruby

Table of Contents

Motivation

The dominant simple plain-text markup languages for the web are
Textile and Markdown. A factor for the popularity of those markup
formats is the widespread availability of simple, free packages for
converting the formats to HTML. For example, the world of
Ruby-powered websites has settled on RedCloth for converting Textile
to HTML.

The default way to convert org-mode files to HTML is the powerful
publishing functionality provided by emacs. However, emacs does
not easiliy integrate into many existing website frameworks.

Org-ruby tries to make it easier to use org-mode files in both
dyanmic and static website generation tools written in
Ruby. Org-ruby is a simple Ruby gem to convert org-mode files to
HTML.

Using Org-ruby

Org-ruby follows the same model as other Ruby markup
libraries. You install the gem:

Walkthrough: Using org-ruby with Webby

Here is an example of how to integrate org-ruby into Webby, a
static website generation tool written in Ruby.

Webby follows a similar pattern to other static site generation
tools (like nanoc, Jekyll, and webgen):

You author website content in text with simple markup

Each page is fed through one or more filters to produce HTML

The HTML is mixed in with layouts to produce the final pages

For a Webby site, a the source for a page may look like this:

---
title: Special Directories
created_at: 2009-12-17
status: Complete
filter:
- erb
- maruku
tags:
- powershell
---
<%= @page.title %>
==================
Special Directories are a set of directories, each of which has a
function that will navigate you to the appropriate directory using
the push-location cmdlet. For example, the function `home` might
navigate to `c:\users\bdewey.`
Install
-------
Copy the module to somewhere in `ENV:PSModulePath`. Then,
InstallModule SpecialDirectories

In the above example, the text is written in Markdown. At the top of
the file, metadata informs Webby to pass the text through two
filters to produce HTML. The first filter, erb, handles embedded
Ruby. In this case, it will replace <%= @page.title %> with the
page title (Special Directories). The second filter uses Maruku to
translate Markdown into HTML.

You can use the exact same pattern to include org-mode files in a
Webby site. For this walkthrough, I assume you already have Webby
installed, and that you've already created a site.

Make sure you have org-ruby installed: sudo gem install
org-ruby.

You need to register a new Webby filter to handle org-mode
content. Webby makes this easy. In the lib/ folder of your
site, create a file orgmode.rb:

Description

Helpful Ruby routines for parsing orgmode files. The most
significant thing this library does today is convert orgmode files
to textile. Currently, you cannot do much to customize the
conversion. The supplied textile conversion is optimized for
extracting "content" from the orgfile as opposed to "metadata."

History

2009-12-29: Version 0.4

The first thing output in HTML gets the class "title"

HTML output is now indented

Proper support for multi-paragraph list items.

See? This paragraph is part of the last bullet.

Fixed bugs:

"rake spec" wouldn't work on Linux. Needed "require 'rubygems'".

#+ENDEXAMPLE

This file will go through the erb and org filters; as defined
in the previous step, the org filter will use org-ruby to
generate HTML.