Building a static website with Emacs and Hugo

September 30, 2018
4 minute read
software emacs hugo

I decided to build a blog as a static website with Hugo as the static site generator. Being an Emacs and Org mode user it’s also clear that I’ll use them for the content creation. Initially I planned to use Gitlab pages for hosting but I couldn’t get it work. So I moved on to Netlify.

This post describes the parts that weren’t immediately obvious for me. Maybe it’s useful for others too.

Preparing Hugo

I did some research which static generator to use and figured out that Hugo might be nice:

So I downloaded it and followed the Quickstart. It explains perfectly what needs to be done to set up the site initially so I won’t repeat that here. Beside the theme used in the tutorial I tried another one and it took me a while to understand how the different parts interact.

Most of the confusion cleared up when I looked in more detail at the examplesite that the minimal theme brings:

For now I’ll use the minimal theme changing some of the templates. Due to the way hugo searches for templates it’s sufficient to move the changed parts to the layouts directory. Then these take precedence over the theme templates. I may want to change more later. So I forked this repo and use my fork instead. As recommended I installed it as a git submodule.

Setting up Emacs

ox-hugo provides the option to create Hugo content from Org subtrees. In this way the complete blog content is in a single file and can be created via the common exporter facility in Org.

So I installed it via use-package and copied the sample file into a ‘org’ directory. Much to my surprise and pleasure the export worked immediately and as expected. What I really like is the ease to setup the frontmatter and include tags via inheritance.

The relevant part of the config is simply

(use-package ox-hugo
  :demand t
  :after ox
  :config (require 'ox-hugo-auto-export))

A beautiful part of it is the auto-export. That means whenever I save my org file the export is done. I configured it via a .dir-locals.el file in the project root as explained on the website. I had to restart Emacs once for it to take effect but then it worked as expected.

Combined with

hugo server -D --navigateToChanged

this allows for almost instant feedback on any changes to the content in my org file.

If you’re interested my complete Emacs config is on GitHub.

Hosting the site

This was the hardest part for me. As mentioned initially I wanted to use Gitlab pages but couldn’t create a user page.

Searching provided several links to so I gave that a try and it worked out nicely. What I like about it is the automatic build of the site. For me it’s enough to push to a remote git repository.

I only encountered a few small issues:

Org mode dependency on htmlize

September 21, 2018
1 minute read
emacs org
comments powered by Disqus