Moving from Jekyll to OrgMode

(An Experience Report)

Adolfo Villafiorita

2020-11-28 Sat 00:00

Created: 2021-07-19 Mon 08:08

Moving From Jekyll to Org Mode

An experience report

Adolfo Villafiorita mailto:adolfo@shair.tech

Shair.Tech https://shair.tech

DataScientia Education http://datascientia.education/cl-2020

Static Website Generators

jekyll.png

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, …

Liquid

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

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!

orgmode.png

  • 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>"
end
puts "</li>"
#+END_SRC

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

Advantages

  • 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).

Examples

Questions

Thanks! Questions?

Adolfo Villafiorita
mailto:adolfo@shair.tech
https://ict4g.net/adolfo