UP | HOME

Support via Liberapay

org-ruby

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 easily integrate into many existing website frameworks.

Org-ruby tries to make it easier to use org-mode files in both dynamic and static website generation tools written in Ruby. Org-ruby is a simple Ruby gem to convert Org mode files to HTML, markdown, or textile. GitHub and GitLab use org-ruby to generate preview for Org mode files, including README.org for project pages.

Using Org-ruby

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

On Debian and Ubuntu Linux you may install it from system repositories

apt install ruby-org

The provided command line tool is handy to test if an Org mode file relies on features not supported by org-ruby

org-ruby -t html README.org >README.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.

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.

  1. Make sure you have org-ruby installed: sudo gem install org-ruby.
  2. 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:

    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-ruby parser to translate org-mode input into HTML.

  3. Create your content. For example:

    ---
    title:              Orgmode Parser
    created_at:         2009-12-21
    status:             Under development
    filter:
      - erb
      - org
    tags:
      - orgmode
      - ruby
    ---
    <%= @page.title %>
    
      Status: <%= @page.status %>
    
    * 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'".
    

    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.

That's all there is to it!

Project history

Brian Dewey developed the gem, the original repository is https://github.com/bdewey/org-ruby.

Later Waldemar Quevedo became the maintainer and currently the gem is built from the https://github.com/wallyqs/org-ruby repository.

See also

Documentation from the orgmode.org/worg/ website (either in its HTML format or in its Org format) is licensed under the GNU Free Documentation License version 1.3 or later. The code examples and css stylesheets are licensed under the GNU General Public License v3 or later.