Building a static website with Emacs and Hugo
September 30, 2018
4 minute readsoftware 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.
I did some research which static generator to use and figured out that Hugo might be nice:
- super simple install both on Linux and Windows
- really fast with live updates on the local server
- a large collection of beautiful themes
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:
- subtitles go into the frontmatter
- additional items in the main menu are added via config.toml directive.
- Anything in a
_index.mdfile is simply added to page independent of further content like posts.
- Obviously it depends on the theme if it is shown.
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
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
1 2 3 4
(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
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 https://netlify.com 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:
- Creating a git submodule using the git protocol doesn’t work for the automated build. This isn’t surprising because that requires ssh authentication which the automated build cannot perform. So I removed the theme and the submodule (deleting the corresponding lines in .gitmodules) and added it again using https.
baseURLmust point to the correct URL. Otherwise the css isn’t picked up and the site looks ugly.
- I had forgotten to set up disqus correctly and it took me a while to figure out what the
disqusShortnameis. Turns out you need to register the site first which provides the shortname.