* Motivation I love Emacs [[http://orgmode.org/][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 [[http://jekyllrb.com/][Jekyll]]*. Jekyll makes deploying static websites fun and pretty.
** Other solutions *** cinsk/jekyll-org I searched for a solution to use these two technologies together and found [[https://github.com/cinsk/jekyll-org/][cinsk/jekyll-org]]. While this seems like a great project, it has some problems:
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.
*** eggcaker/jekyll-org Only after completing this project did I discover the project which would have been perfect for my purposes: [[https://github.com/eggcaker/jekyll-org][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:
** 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 [[http://jekyllrb.com/docs/plugins/#converters][converter]] for a new markup language. To make the job even easier there already exists a ruby based org-to-html converter [[https://github.com/bdewey/org-ruby][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
*** Long version To use ~jekyll-org-mode-converter~ with Jekyll, you need to have Ruby RubyGems and Jekyll installed. See how to do that [[http://jekyllrb.com/docs/installation/][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 [[http://jekyllrb.com/docs/plugins/][security reasons]]. This implies that to use [[https://help.github.com/articles/using-jekyll-with-pages/][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
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 [[http://tjaartvdwalt.github.io][my personal website]]. You can see the source code [[https://github.com/tjaartvdwalt/tjaartvdwalt.github.io][here]].
** Contributing to jekyll-org-mode-converter
** Copyright
Copyright (c) 2015 Tjaart van der Walt. See LICENSE.txt for further details.