jekyll-org

Looking for a New Maintainer

Notice: I am currently not really using ruby and jekyll right now, and I am looking for someone who is interested and willing to take over its maintenance. If you’re interested, please contact me using one of the methods below: Send an email to: eggcaker@gmail.com Leave a message in the issues.

Overview

This plugin adds Org mode support to Jekyll and lets you write posts and pages in Org.

Related Projects

What’s the difference with org2jekll You don’t need to any org-publish-project-alist to starting write post, just start with any editor that org-mode supported

What’s the difference with org-jekyll? You don’t need to add some alien yaml in your org-mode file. You add specific org-mode headers and this will be used to format the jekyll post.

What’s the difference with happyblogger? No more external ruby script.

Requirements

Jekyll
org-ruby

Installation

Short version

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

Include the gem in your _config.yml
Include the gem in Gemfile

Long version

To use jekyll-org 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' , '>= 3.0.0'
gem 'jekyll-org', '>= 1.1.0'

Install the gems with bundler:

bundle install

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

plugins:
  - jekyll-org

Usage

Create a new file with .org extension in _posts, and write the post with Org. That is all! Generate your Jekyll site as you usually do.

Front matter

Instead of YAML the front matter is configured in the usual Org way, with no lines.

Below is an example of an Org post, featuring front matter, tags, tables, liquid templating and syntax highlighting. To render this example, remove the leading hash symbols (#) at #+begin_src and #+begin_end beforehand (this is a workaround for GitHub’s org rendering).

#+TITLE: Jekyll and Org together
#+LAYOUT: post
#+TAGS: jekyll org-mode "tag with spaces"

This is a blog post about Jekyll and Org mode.

** org-table demo 

   | a | b | c | d | e |
   |---+---+---+---+---|
   | 1 | 2 | 3 | 4 | 5 |

** Liquid demo 
   #+liquid: enabled
   #+foo: hello world
   {{ page.foo }}

   or

   {{ site.time | date_to_xmlschema }}
   
** Code highlighting
   Jekyll-org also offers powerful support for code snippets:
   ##+begin_src  ruby 
     def print_hi(name)
       puts "Hi, #{name}"
     end
     print_hi('Tom')

     #=> prints 'Hi, Tom' to STDOUT.
   ##+end_src

The value of #+TAGS is parsed into a list by splitting it on spaces, tags containing spaces can be wrapped into quotes.

Liquid templating

By default the all content is exported to raw HTML with org-ruby, but you can add #+liquid: whatevervalue= in the header. Then you can use Liquid tags.

For example, if your Org file contains

#+liquid: enabled
#+foo: hello world

{{ page.foo }}

or

{{ site.time | date_to_xmlschema }}

then you will get output like

<p>hello world</p>
<p>or</p>
<p>2014-07-02T08:20:28+08:00</p>

Site wide config

Alternatively, if you’d rather enable liquid by default for every org file being converted, you can enable it in your _config.yml file.

org:
  liquid: true

Source code highlighting

To enable source code highlighting, run bundle add pygments.rb. If your Jekyll theme has built-in support for syntax highlighting, you’re all set! Otherwise, add a pygments-compatible CSS file to your site’s /assets/css/ folder. You can find a bunch of CSS themes for pygments in this repository, or create your own (some related pygments documentation is here).

Then, add a source code block as you would in Org, for example Ruby:

require 'rubygems'
require 'org-ruby'
data = IO.read(filename)
puts Orgmode::Parser.new(data).to_html

And the output will have code highlighting:

require 'rubygems'
require 'org-ruby'
data = IO.read(filename)
puts Orgmode::Parser.new(data).to_html

Author

eggcaker <eggcaker@gmail.com>

License

MIT