Customizing and publishing a static website with Emacs and org-mode is quite easy. Like with almost every static website generator you have rules to convert a specific set of files from one format into another. The two most important converters for website publishing in emacs are

• org-html-publish-to-html converts org files to html files
• org-publish-attachment copies files from input to output location (identity function, no conversion happens)

As depicted in the following images, org-publish-attachment is used for static content like stylesheets and images, while org-html-publish-to-html is used to convert .org files to .html files.

To specify the set of files on which a converter acts, one specifies an element in the org-publish-project-alist list:

(setq org-publish-project-alist
      '(("orgfiles"
         :base-directory "."
         :base-extension "org"
         :publishing-directory "./build/html"
         :recursive t
         :publishing-function org-html-publish-to-html)
        ("images"
         :base-directory "img"
         :base-extension "png"
         :publishing-directory "./build/html/img"
         :publishing-function org-publish-attachment)
        ("website"
         :components ("orgfiles" "images"))))

In this listing a converter (a project in org-mode) named orgfiles is defined for recursively converting all .org files into the folder ./public and a converter named images which copies all files with the extension .png in the folder ./img into the folder ./public/img. It is this simple!

This configuration can be put into a file publish-html.sh and called from a Makefile as

./publish-html.sh

this involves some emacs script trickery which is explained here in all it’s detail.

By employing GNU Guix to build the website we can solve several issues:

• document (and collect) all necessary build tools
• reproduce the build in the future, on another machine or architecture
• build in a containerized environment

To achieve this, a manifest file and a channels file is sufficient. Our manifest file manifest.scm contains the following

(specifications->manifest
 '("emacs"
   "font-linuxlibertine"
   "font-fira-code"))

which is Emacs for compiling the source and a regular and a monospace font for serving in the website.

The channels file channels.scm is even easier, it serves pinning the software defined in the manifest file and can be updated with

guix describe --format=channels > channels.scm

Now for building the website, a containerized environment can be started with guix shell (inside the directory where manifest.scm resides) and subsequently the build command in listing 1 can be called.

Naturally you want to tweak the appearance of your website to your desired style. There are several ways to achieve this

1. use the customization options for publishing
2. derive a new template from an existing one

For most use cases 1 is sufficient, but if you want more control over the HTML elements you have to use 2. We want go into detail for 2 (look up org-export-define-derived-backend) and will focus on 1 instead.

A feed is a XML document with a list-like structure which in case of a blog has an entry for each blog post. The content of this entry can be choosen arbitrarely but in most cases it contains part or the whole blog post.

• The inspiration for the styling came mostly from Dave Thompson’s website
• Thomas Ingram’s blog introduced me to org-mode sitemap’s
• Basti did a good job explaining emacs script trickery
• A nice blog with an introduction to ox-rss.el