- Other solutions
- My approach
- How to use the converter
- Deploying to Github
- Contributing to jekyll-org-mode-converter
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.
I searched for a solution to use these two technologies together and found cinsk/jekyll-org. While this seems like a great project, it has some problems:
- It is not compatible with recent versions of Org mode
- The workflow seems pretty complex.
To convert your documents you need to run a separate make file that runs some elisp to convert your org files to html, and then run Jekyll in a sub directory on the converted html to build the resulting website.
While I understand that hacking Elisp always seems like the appropriate course of action for many experienced Emacs users, I don’t believe every problem is best solved inside Emacs.
Only after completing this project did I discover the project which would have been perfect for my purposes: eggcaker/jekyll-org This project is very similar to mine, and (at the moment) is more mature. For example I have not thought about how to handle Liquid code in my HTML yet.
I thought about abandoning the project, but I see 2 differences that makes it worth saving in my view:
- eggcaker/jekkyll-org runs as a Jekyll plugin, while my project gets installed as a Gem.
- My project has better documentation. I think the section on how to deploy to GitHub is especially useful.
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
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
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
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:
To use the new converter add the following line to your
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
For relative links to work properly you will also need to set the
baseurl property in your
Also, you should create a file called
.nojekyll to prevent GitHub from trying to build the Jekyll pages in the src directory.
index.html to redirect to the
<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.
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.
Copyright (c) 2015 Tjaart van der Walt. See LICENSE.txt for further details.