Skip to content

Latest commit

 

History

History
149 lines (111 loc) · 6.32 KB

README.org

File metadata and controls

149 lines (111 loc) · 6.32 KB
Raw

jekyll-org-mode-converter

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.

Other solutions

cinsk/jekyll-org

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.

eggcaker/jekyll-org

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.

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.

Copyright

Copyright (c) 2015 Tjaart van der Walt. See LICENSE.txt for further details.