jekyll-org-mode-converter

Motivation
Other solutions
My approach
How to use the converter
Deploying to Github
Example
Contributing to jekyll-org-mode-converter
Copyright

Motivation

I love Emacs Org mode and I try to write all my documents in Org mode and export them everywhere. Unfortunately Org mode’s default html output is rather plain. Enter Jekyll. Jekyll makes deploying static websites fun and pretty.

My approach

I decided to approach the problem from a Jekyll point of view. I wanted to use the standard Jekyll workflow, only with Org mode files instead of Markdown files.

Luckily Jekyll makes it easy to write a converter for a new markup language. To make the job even easier there already exists a ruby based org-to-html converter org-ruby. Org-ruby is what Github uses to render Org mode files (like this README) to html.

How to use the converter

Short version

For experienced Jekyll users, you need to do 2 things to get jekyll-org-mode-converter to work

Install the gem
Include the gem in your _config.yml

Long version

To use jekyll-org-mode-converter with Jekyll, you need to have Ruby RubyGems and Jekyll installed. See how to do that here.

Create a new Jekyll project my-site run:

jekyll new my-site

Create a Gemfile in the root of the project, and add at least the following lines:

source 'https://rubygems.org'

gem 'jekyll' , '>= 2.5.3'
gem 'jekyll-org-mode-converter' , '>= 0.1.1'

Install the gems with bundler:

bundle install

To use the new converter add the following line to your _config.yml:

gems: [jekyll-org-mode-converter]

Now write your jekyll posts in Org mode!

To build your site run:

bundle exec jekyll build

and to serve your site run:

bundle exec jekyll serve

Deploying to Github

One of the cool features of Jekyll is that you can deploy Jekyll websites to Github by simply pushing the Jekyll code to your GitHub remote. Unfortunately for us, Github does not allow you to run custom plugins for security reasons. This implies that to use Jekyll with GitHub Pages you ideally need to write posts in Markdown. But we love Org mode and we don’t want to learn yet another markup language.

Luckily, all is not lost. We will need to build our site locally and push the static pages to GitHub. My approach is to keep both the Jekyll code and the static HTML in a single repository, which I organize in the following way:

.
|
|-- src/         (the root of my jekyll project)
|
|-- www/         (resulting site goes here)
|
|-- .nojekyll    (prevents GitHub from building our Jekyll code)
|
|-- index.html   (redirects users to www/)

You need to configure the destination directory by adding the following line in your _config.yml

destination: ../www

For relative links to work properly you will also need to set the baseurl property in your _config.yml

baseurl: /www

Also, you should create a file called .nojekyll to prevent GitHub from trying to build the Jekyll pages in the src directory.

Create index.html to redirect to the wwww directory

<html>
<meta http-equiv="refresh" content="0; url=www" />
</html>

Locally you should run jekyll build on the src directory and push the results to GitHub.

Example

To see an example of the Github deployment method in action, have a look at my personal website. You can see the source code here.

Contributing to jekyll-org-mode-converter

Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet.
Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it.
Fork the project.
Start a feature/bugfix branch.
Commit and push until you are happy with your contribution.
Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.