Migrating from Jekyll to org-mode and Github Actions

While I could have most of the configuration in my ~/.emacs.d/init.el, I wanted a self-contained solution, not depending on my personal emacs configuration being available.

There are a bunch of emacs options that help achieving this:

$ emacs --help
...
--batch                     do not do interactive display; implies -q
...
--no-init-file, -q          load neither ~/.emacs nor default.el
...
--load, -l FILE         load Emacs Lisp FILE using the load function
...
--funcall, -f FUNC      call Emacs Lisp function FUNC with no arguments
...

With these options, we can put all our configuration and helper functions in a lisp file, call emacs as a script engine, skip our personal configuration, have emacs load the file with the configuration, and call a function to run everything.

org-mode includes an Export subsystem with several target formats (ASCII, beamer, HTML, etc). Every backend/converter is a set of functions that take already parsed org-mode structures (eg. a list, a timestamp, a paragraph) and converts it to the target format. Worg, a section of the Org-mode web site that is written by a volunteer community of Org-mode fans, provide documentation on how to define an export backend (org-export-define-backend). From here is important to understand the filter system and org-export-define-derived-backend, which allows to define a backend by overriding an existing one. This is what I will end using to tweak, for example, how timestamps are exported.

org-mode includes a publishing management system that helps exporting a interlinked set of org files. There is a nice tutorial also available.

Using org-publish boils down to defining a list of components (blog posts, assets, RSS), their options (base directory, target directory, includes/excludes, publishing function) being the publishing function one of the most interesting ones, as org comes with a few predefined ones eg. org-html-publish-to-html to publish HTML files and org-publish-attachment to publish static assets. The most important thing to learn here is that you can wrap those in your own to do additional stuff and customize publishing very easily. I use this for example, to skip draft posts or to write redirect files for certain posts in addition to the post itself.

├── CNAME
├── css
│   ├── index.css
│   └── site.css
├── index.org
├── Makefile
├── posts
│   ├── 2019-10-31-some-post
│   │   └── index.org
│   ├── 2014-06-11-other-post
│   │   ├── images
│   │   │   ├── someimage.png
│   │   │   └── another-image.png
│   │   └── index.org
│   ├── archive.org
│   └── posts.org
├── public
├── publish.el
├── README.org
├── snippets
│   ├── analytics.js
│   ├── postamble.html
│   └── preamble.html
└── tutorials
    └── how-to-something
        └── index.org

Inside the directory tree, you can find:

• a publish.el file with the org-publish project description and all the support code and helper functions
• a CNAME file for telling Github Pages my domain name
• a folder with a CSS file for all the site. Another one that is included only on the index page
• a Makefile that just calls emacs with the parameters we described above and calls the function duncan-publish-all
• a subdirectory for each post, and another one for tutorials
• a public directory where the output files are generated and the static assets copied
• a snippets directory with the preamble, postamble and Google analytics snippets

The main file containing code and configuration includes a few custom publishing functions that are used as hooks for publishing and creating sitemaps.

The org-publish project (org-publish-project-alist) is defined in the variable duncan–publish-project-alist, and defines the following components:

• blog

  This components reads all org files in the ./posts/ directory, and exports them to HTML using duncan/org-html-publish-post-to-html as the publishing function.

  This function injects the date as the page subtitle in the property list before delegating to the original function. This is a common pattern that you can use to override the publishing function. Note that subtitle is a recognized configuration property of the HTML export backend.

(defun duncan/org-html-publish-post-to-html (plist filename pub-dir)
  "Wraps org-html-publish-to-html.  Append post date as subtitle to PLIST.  FILENAME and PUB-DIR are passed."
  (let ((project (cons 'blog plist)))
    (plist-put plist :subtitle
               (format-time-string "%b %d, %Y" (org-publish-find-date filename project)))
    (duncan/org-html-publish-to-html plist filename pub-dir)))

The function also checks the #+REDIRECT_TO property, and generates redirect pages accordingly, by spawning another export to a different path in the same pub_dir.

This component is configured with a sitemap function which, even if goes through all posts, it is programmed to take only a few ones and write an org file with links to them. This file (posts.org) is then included in index.org and used as the list of recent posts.

• archive-rss

  This component also operates on /.posts/, but instead of generating HTML, it uses the RSS backend to generate the full site archive as RSS.

  The sitemap function is also configured, like in the blog component, but this function generates an org file with all posts, not just the latest ones. The sitemap-format-entry function is shared between the sitemaps functions, as the list of posts looks the same.

• site

  The rest of the content of the site, including the index.org page and the generated org files for the archive (archive.org) and latest posts (posts.org).

• assets

  All files that are just copied over

• tutorials

  It works just like posts, but I setup each (don’t expect to have many) to use the ReadTheOrg theme. It uses the default HTML publishing function.