Abstract
The emacs org-mode is a simple, text markup based outliner and personal organizer with a bunch of features for creating extensively hyperlinked notes. By writing simply formatted text and exporting to HTML, you can create web sites. If combined with jekyll, it allows creation of a website with integrated blog. The best part is that no software is required server side, making the generated site virtually unhackable. Org-mode and jekyll compile the site to static html, and can be made responsive with css and javascript (e.g., bootstrap).
Introduction
My personal homepage http://www.hpcf.upr.edu/~humberto/ has for many years been generated with GTML, a static website generator that combines several tools. My version is ancient, and I’ve been wanting to update my (rather plain) website to a new style for some time, so I started looking around for alternatives.
I want my site to look nicer than the old one, so I started with bootstrap, a javascript library for creating good looking pages with minimal effort. To use bootstrap, you need to write your entire page in html. Writing plain html is a pain, so I searched for template languages that work with bootstrap. Jekyll is the site generator for github-pages, and works nicely with bootstrap. Jekyll supports various markup languages (principally markdown) out of the box, simplifying website generation.
I remembered an article on using org-mode and jekyll, and decided to try combining them for my site. It takes quite a bit of setup work, but the result is very flexible, and I think it looks quite nice.
Methods
I started by creating a jekyll site following the quickstart. Then I modified the default template to include bootstrap. At this stage, it’s convenient to use the jekyll serve command to test the site. Once the jekyll + boostrap is working, I created a directory for the org project. I moved the jekyll site into the project directory, and created an org directory parallel to the jekyll directory, as recommended in the tutorial.
The final step is to create a project file. I created a project.el file in the project directory, where I define the org-publish project. I had some trouble because the version of org complained about argument count mismatches. Following the instructions in this stack overflow post solved the issue.
(require 'ox-publish)
(require 'ox-html)
;(require 'org-publish)
(setq org-publish-project-alist
'(
("org-humberto"
;; Path to your org files.
:base-directory "~/src/web/test-org-jekyll/org/"
:base-extension "org"
;; Path to your Jekyll project.
:publishing-directory "~/src/web/test-org-jekyll/jekyll/"
:recursive t
:publishing-function org-html-publish-to-html
;; :headline-levels 4
;; :html-extension "html"
:body-only t ;; Only export section between <body> </body>
:with-toc nil ;; don't export toc, it clobbers the yaml front matter
)
("org-static-hoz"
:base-directory "~/src/web/test-org-jekyll/org/"
:base-extension "css\\|js\\|png\\|jpg\\|gif\\|pdf\\|mp3\\|ogg\\|swf\\|php"
:publishing-directory "~/src/web/test-org-jekyll/jekyll"
:recursive t
:publishing-function org-publish-attachment)
("hoz" :components ("org-humberto" "org-static-hoz"))
))
After evaluating the above code, running C-c C-e pops up a page of export options, and selecting P, x exports a named project. This pulls all the org files from the org tree, and publishes html in the jekyll tree.
Results
The combination of org-mode, jekyll and bootstrap makes a simple website generator with lots of features. There are lots of other ways to do the same thing, but org-mode has a lot of smarts on the editing side, making life simpler for the writer (e.g., links are live in the markup language).
There are two features I still don’t know how to emulate in the new setup. GTML can define new macros, like:
define doi(uri) <a href="http://dx.doi.org/uri">doi: uri</a>
Jekyll allows includes and variables, but I’m not sure I can define a parametrized macro like the above. Fortunately, org-mode can provide the same functionality. Here’s org-mode’s version of macros:
#+MACRO: doi [[http://dx.doi.org/$1][doi:$1]]
The other feature I like about GTML is that it can generate a site index with all the files defined in the project, and next, previous and up links on each page. I know org mode can do the same, but I haven’t yet read how to do it and integrate into this site.