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)
7 #+EMAIL: bdewey@gmail.com
12 [[file:index.org][{Back to Worg's index}]]
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
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.
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
34 =Org-ruby= follows the same model as other Ruby markup
35 libraries. You install the gem:
38 sudo gem install org-ruby
41 Then, to convert an org-file to HTML in your Ruby code:
47 data = IO.read(filename)
48 puts Orgmode::Parser.new(data).to_html
51 * Walkthrough: Using org-ruby with Webby
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.
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]]):
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
63 For a Webby site, a the source for a page may look like this:
67 title: Special Directories
68 created_at: 2009-12-17
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.`
87 Copy the module to somewhere in `ENV:PSModulePath`. Then,
89 InstallModule SpecialDirectories
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.
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.
103 1. Make sure you have =org-ruby= installed: =sudo gem install
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=:
112 Webby::Filters.register :org do |input|
113 Orgmode::Parser.new(input).to_html
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:
123 title: Orgmode Parser
124 created_at: 2009-12-21
125 status: Under development
135 Status: <%= @page.status %>
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."
148 ** 2009-12-29: Version 0.4
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.
154 See? This paragraph is part of the last bullet.
157 - "rake spec" wouldn't work on Linux. Needed "require 'rubygems'".
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
164 That's all there is to it!