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 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.
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
x exports a named project. This pulls all the org files from the org tree, and publishes html in the jekyll tree.
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.