Blogging with ox-hugo

You may found that the blogging style is some kind of difference, because I am blogging with ox-hugo now. I’m writing this down in case someone want to try ox-hugo and need help

The reasons I’m switching to ox-hugo

I thought the original org support from hugo is enough, though there’re drawbacks, such as:

  • hugo does not support org table feature
  • hugo shows a link to a image instead of the image itself (it is now fixed, btw)

I can use a list for most cases of table, but image, there’s no way but to embed an html img tag. Yes using html tags directly is not complicated, but # more not work is bothering for me, it feels realy bad everytime I type <!--more-->, and it looks like hugo is not going to fix this issue.

Some reader of my other post suggest me to try ox-hugo, which I’ve heard since I started to use hugo. But I didn’t try it because I want to save time on learning tools. And I have to admit that packages of emacs are hard to configure for me, including ox-hugo :)

But it turned out that I don’t need a lot of settings or functions to configure ox-hugo, if you want to try ox-hugo quickly, let’s get started.


You’re assumpted to have experience on the following fields, these fields are not covered in this post

emacs org

A text file like markdown, you can’t use ox-hugo if you don’t know org mode.


Your emacs should be configured to be able to install packages using melpa.

hugo and your configured hugo site

ox-hugo simply converted org files to markdown files, which are the first class citizens in hugo :), but you still need hugo to generate your site.


Installing ox-hugo

Use M-x list-packages to open package list, move the cursor to ox-hugo, press i to mark it as install, press x to execute the installation.

Configuring ox-hugo

Open your init.el file and add the following settings, restart emacs and you’re done.

(with-eval-after-load 'ox
  (require 'ox-hugo))
(require 'ox-hugo-auto-export)  ;; update: we don't need this any more

Building blog template

We could now write our blogs now, but we could create a template file now, to simplify the blog writing.

Let’s create an ox-hugo folder in our hugo site folder. And create a inside the folder, file content refers to this file.

Configuration is listed here (yes we are going to use table):

Name Configuration
HUGO_BASE_DIR Site folder relative to this folder
HUGO_SECTION Ox-hugo output folder, the same folder you place your org/md files before
HUGO_WEIGHT Post ordering weight
HUGO_AUTO_SET_LASTMOD Modify last mod time automatically
TITLE Post title
HUGO_TAGS Post tags
HUGO_DRAFT Is this a draft
hugo: more Sperator between intro and content
Footnotes Configurations to save file
org-hugo-auto-export-on-save Auto export on save

There’s only one config you must modify: HUGO_SECTION, which is differed by folder names, the others could be changed as we need.

Update: org-hugo-auto-export-on-save is deprecated, use the following line instead:

# eval: (org-hugo-auto-export-mode)

Writing Post

Now we can use the template to write post, when we save the file, ox-hugo will translate our org file to markdown and put it to the output folder, does it feel like we are the first class citizens again? Yes though it is just illusion :)


It’s not that hard to try ox-hugo, install, configure, template, then we can writing our post.