Moving from Jekyll to OrgMode

(An Experience Report)

Adolfo Villafiorita

2020-11-28 Sat 00:00

Created: 2021-03-21 Sun 17:33

Moving From Jekyll to Org Mode

An experience report

Adolfo Villafiorita


DataScientia Education

Static Website Generators


Jekyll is a static website generator written in Ruby

  • Input files contain:
    • Metadata describing the file content (title, tags, …)
    • Content to be published (written in some markup language)
  • “Dynamic” pages are generated from the metadata using Liquid, a language which supports iterations, conditions, …


  {% for post in site.posts %}
      <a href="{{ post.url }}">{{ post.title }}</a>
  {% endfor %}

Org Mode as a Markup language for Jekyll

  • Over the years I moved systematically from Markdown to Org Mode:
    • MathJax
    • Diagram generation
    • Gnuplot
    • Multiple backends
    • Babel
  • Org Mode can be used to write pages understood by Jekyll, using the jekyll-org gem

Org Mode

Org Mode is (also) a static website generator!


  • but…
    • Support for templating is not obvious (but, see, for instance, Org-THTML)
    • (apparently) little support for “dynamic” content (various packages customize Org Mode to support blogging)

Babel to the rescue!

Babel can generate all the “dynamic” content, for instance, by executing a Ruby script which reads the meta content of all pages

#+BEGIN_SRC ruby :exports results :results output html
require 'org-ruby'
require 'date'

# metadata.rb imitates Jekyll and it creates a list of the files belonging to the site
load "../_scripts/metadata.rb"
posts = Metadata.collect "*"

puts "<li>"
posts.each do |post|
  puts "<a href=\"#{post[:relative_url]}\">#{post.title}</a>"
puts "</li>"

Include and Elnode to the Rescue

  • Org Mode #+INCLUDE: can be used to inject HTML in all pages (e.g., navigation)
  • Elnode can be used to locally preview a website before deploying it
  • A quick hack website.el defining two emacs-lisp functions: website-server-start and website-deploy


  • All content written in Org Mode
  • Publishing based on the standard machinery provided by Org Mode
  • Graceful failure: can publish a single file
  • Self-documented: the declaration of how the site is built can be deployed with the site itself (e.g project specification of my homepage).



Thanks! Questions?

Adolfo Villafiorita