org-tutorials/org-ruby.org

   1 #+OPTIONS:    H:3 num:nil toc:nil \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
   2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
   3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c)
   5 #+TITLE:      org-ruby
   6 #+AUTHOR:     Brian Dewey
   7 #+EMAIL:      bdewey@gmail.com
   8 #+LANGUAGE:   en
   9 #+PRIORITIES: A C B
  10 #+CATEGORY:   worg
  11
  12 [[file:index.org][{Back to Worg's index}]]
  13
  14 * Motivation
  15
  16   The dominant simple plain-text markup languages for the web are
  17   [[http://www.textism.com/tools/textile/][Textile]] and [[http://daringfireball.net/projects/markdown/][Markdown]]. A factor for the popularity of those markup
  18   formats is the widespread availability of simple, free packages for
  19   converting the formats to HTML. For example, the world of
  20   Ruby-powered websites has settled on [[http://redcloth.org/][RedCloth]] for converting Textile
  21   to HTML.
  22
  23   The default way to convert org-mode files to HTML is the powerful
  24   publishing functionality provided by =emacs=. However, =emacs= does
  25   not easiliy integrate into many existing website frameworks.
  26
  27   [[http://github.com/bdewey/org-ruby][=Org-ruby=]] tries to make it easier to use org-mode files in both
  28   dyanmic and static website generation tools written in
  29   Ruby. =Org-ruby= is a simple Ruby gem to convert org-mode files to
  30   HTML.
  31
  32 * Using Org-ruby
  33
  34   =Org-ruby= follows the same model as other Ruby markup
  35   libraries. You install the gem:
  36
  37   #+BEGIN_EXAMPLE
  38   sudo gem install org-ruby
  39   #+END_EXAMPLE
  40
  41   Then, to convert an org-file to HTML in your Ruby code:
  42
  43   #+BEGIN_EXAMPLE
  44   require 'rubygems'
  45   require 'org-ruby'
  46
  47   data = IO.read(filename)
  48   puts Orgmode::Parser.new(data).to_html
  49   #+END_EXAMPLE
  50
  51 * Walkthrough: Using org-ruby with Webby
  52
  53   Here is an example of how to integrate =org-ruby= into [[http://webby.rubyforge.org/][Webby]], a
  54   static website generation tool written in Ruby.
  55
  56   Webby follows a similar pattern to other static site generation
  57   tools (like [[http://nanoc.stoneship.org/][nanoc]], [[http://jekyllrb.com/][Jekyll]], and [[http://webgen.rubyforge.org/][webgen]]):
  58
  59   - You author website content in text with simple markup
  60   - Each page is fed through one or more /filters/ to produce HTML
  61   - The HTML is mixed in with layouts to produce the final pages
  62
  63   For a Webby site, a the source for a page may look like this:
  64
  65   #+BEGIN_EXAMPLE
  66   ---
  67   title:           Special Directories
  68   created_at:      2009-12-17
  69   status:          Complete
  70   filter:
  71     - erb
  72     - maruku
  73   tags:
  74     - powershell
  75   ---
  76   <%= @page.title %>
  77   ==================
  78
  79   Special Directories are a set of directories, each of which has a
  80   function that will navigate you to the appropriate directory using
  81   the push-location cmdlet. For example, the function `home` might
  82   navigate to `c:\users\bdewey.`
  83
  84   Install
  85   -------
  86
  87   Copy the module to somewhere in `ENV:PSModulePath`. Then,
  88
  89       InstallModule SpecialDirectories
  90   #+END_EXAMPLE
  91
  92   In the above example, the text is written in [[http://daringfireball.net/projects/markdown/][Markdown]]. At the top of
  93   the file, metadata informs Webby to pass the text through two
  94   /filters/ to produce HTML. The first filter, =erb=, handles embedded
  95   Ruby. In this case, it will replace ~<%= @page.title %>~ with the
  96   page title (=Special Directories=). The second filter uses [[http://maruku.rubyforge.org/][Maruku]] to
  97   translate Markdown into HTML.
  98
  99   You can use the exact same pattern to include org-mode files in a
 100   Webby site. For this walkthrough, I assume you already have Webby
 101   installed, and that you've already created a site.
 102
 103   1. Make sure you have =org-ruby= installed: =sudo gem install
 104      org-ruby=.
 105   2. You need to register a new Webby filter to handle org-mode
 106      content. Webby makes this easy. In the =lib/= folder of your
 107      site, create a file =orgmode.rb=:
 108
 109      #+BEGIN_EXAMPLE
 110      require 'org-ruby'
 111
 112      Webby::Filters.register :org do |input|
 113        Orgmode::Parser.new(input).to_html
 114      end
 115      #+END_EXAMPLE
 116
 117      This code creates a new filter, =org=, that will use the
 118      =org-ruby= parser to translate org-mode input into HTML.
 119   3. Create your content. For example:
 120
 121      #+BEGIN_EXAMPLE
 122 ---
 123 title:              Orgmode Parser
 124 created_at:         2009-12-21
 125 status:             Under development
 126 filter:
 127   - erb
 128   - org
 129 tags:
 130   - orgmode
 131   - ruby
 132 ---
 133 <%= @page.title %>
 134
 135   Status: <%= @page.status %>
 136
 137 * Description
 138
 139   Helpful Ruby routines for parsing orgmode files. The most
 140   significant thing this library does today is convert orgmode files
 141   to textile. Currently, you cannot do much to customize the
 142   conversion. The supplied textile conversion is optimized for
 143   extracting "content" from the orgfile as opposed to "metadata."
 144
 145
 146 * History
 147
 148 ** 2009-12-29: Version 0.4
 149
 150    - The first thing output in HTML gets the class "title"
 151    - HTML output is now indented
 152    - Proper support for multi-paragraph list items.
 153
 154      See? This paragraph is part of the last bullet.
 155
 156    - Fixed bugs:
 157      - "rake spec" wouldn't work on Linux. Needed "require 'rubygems'".
 158        #+END_EXAMPLE
 159
 160      This file will go through the =erb= and =org= filters; as defined
 161      in the previous step, the =org= filter will use =org-ruby= to
 162      generate HTML.
 163
 164   That's all there is to it!