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
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
Org-ruby is a simple Ruby gem to convert org-mode files to
Org-ruby follows the same model as other Ruby markup
libraries. You install the gem:
sudo gem install org-ruby
Then, to convert an org-file to HTML in your Ruby code:
require 'rubygems' require 'org-ruby' data = IO.read(filename) puts Orgmode::Parser.new(data).to_html
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.
- 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
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
require 'org-ruby' Webby::Filters.register :org do |input| Orgmode::Parser.new(input).to_html end
This code creates a new filter,
org, that will use the
org-rubyparser to translate org-mode input into HTML.
Create your content. For example:
— title: Orgmode Parser createdat: 2009-12-21 status: Under development filter:
— <%= @page.title %>
Status: <%= @page.status %>
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."
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.
- "rake spec" wouldn't work on Linux. Needed "require 'rubygems'". #+ENDEXAMPLE
This file will go through the
orgfilters; as defined in the previous step, the
orgfilter will use
org-rubyto generate HTML.
That's all there is to it!