quickstart: hugo and org

Intro

With hugo you can write content for your website / blog in a plain text format and it will generate HTML, CSS and JS for your website. It’s awesome; in a short amount of time you can have a new website up that’s easy to update and maintain. Out of the box hugo does support various plain text document formats: markdown, HTML, org and more.

I think it is awesome that there is already support for org files in the hugo tool-chain (go-org) and it is pretty darn complete! However, it only acts as a parser, while org-mode’s export engine a lot more (code eval, filtering trees and much, much more). go-org works really well and if you don’t care about anything that org export does, then I’d suggest you just use it!

For me, I want to be able to leverage org export and all the functionality that entails. Luckily, there is a package: ox-hugo. In this post I will show you how to use hugo and ox-hugo to publish your website. I won’t go into to too much depth, but at the end I’ll give you some suggestions on what might be next for you.

Setup

hugo

The very first thing you need to do is install hugo. Chances are your package manager will have it, but if you can’t find it you can get instructions to install here. With that installed, find a spot on your computer for your new blog to live and from a terminal run hugo new site name-of-your-blog. That will have generated a directory called name-of-your-blog (or whatever you called it) and the basic directory layout for hugo.

With the skeleton of our site in place we need to choose a theme. Don’t fret too much about this, you can always change this later or make your own. Head over to themes.gohugo.io and find a theme you like. When you’ve found one click on it and then on it’s download button. Chances are that took you to the theme’s github page. Rather than use git we’ll just snag a zip of the theme to keep things simple.

Add /archive/master.zip to the end of the github URL to download a zip of the theme. Extract the zip file into ./themes directory inside of your hugo site. The folder it extracts likely is not the name of your theme, so you’ll want to rename the folder to your theme’s name. For example, the folder that was extracted for me was hugo-theme-codex-master, so I renamed it to codex. With the theme downloaded and in the right spot let’s tell hugo we want to use our theme. Edit config.toml and add the following to the bottom:

theme = "your-theme-name"
sectionPagesMenu = "main"

Adding sectionPagesMenu will add menu items when we start to add some content. This is everything we need to do to start using hugo. If you want a more in-depth look at hugo, then take a look at their documentation.

ox-hugo

We need to setup ox-hugo now. I use doom-emacs and setting up ox-hugo is straight forward. You only need to add the +hugo flag to the org module in your init.el, (org +hugo). Then run doom sync. Otherwise I’m going to assume you have emacs and some kind of package manager or distribution through which you can get the package ox-hugo. Reference their documentation for further installation advice.

With the new exporter installed we can setup our org file for our content. Create an org file called content.org at the root of the hugo site with the content:

#+HUGO_BASE_DIR: ./
#+HUGO_SECTION: posts

* Home
:PROPERTIES:
:EXPORT_HUGO_SECTION:
:EXPORT_FILE_NAME: _index
:END:
Home is where emacs is.

* Motivation
:PROPERTIES:
:EXPORT_HUGO_SECTION:
:EXPORT_FILE_NAME: about
:END:
I'm blogging because I want to.

* Posts
** First post
   :PROPERTIES:
   :EXPORT_DATE: 2020-07-17
   :EXPORT_FILE_NAME: first_post
   :END:
 This is my first post. Kind of an obligatory "Hello world".

** Second post
   :PROPERTIES:
   :EXPORT_DATE: 2020-07-18
   :EXPORT_FILE_NAME: second_post
   :END:
 This is my second post where I'll actually start my blog.

* Notes
  Notes on my blog

There are two properties that are required when using ox-hugo and those are HUGO_BASE_DIR and HUGO_SECTION. The first tells ox-hugo where the root of your hugo site is and the second tells it where you want the content you write in here to be located. The other notable piece of configuration is the property EXPORT_FILE_NAME, which is what allows us to use one file to manage our entire blog.

Hit C-c C-e H A to export your org-file to hugo. Start your hugo server again if it isn’t still running and navigate to http://localhost:1313. You should have a shiny blog post staring you in the face!

What’s next?

There are a lot of things that I missed and this really isn’t a full, end-to-end setup and workflow guide, so here are some ideas of what you could do next:

  1. Host your hugo site on github pages
  2. Setup your hugo site using git and your theme using a git submodule
  3. Learn more about hugo and / or ox-hugo

835 Words

2020-07-20 00:00 -0600