Table of Contents

Yesterday, I’ve rewritten my blog using Hugo , but with a spin; instead of using the usual markdown -> hugo -> html, I’ve went with ox-hugo which adds another layer to this process so it becomes org -> markdow -> hugo -> html and I’ve done this for a few reasons

  • I am already using org-mode for my private notes, if I ever decide to make a note public that would be very easy with both my private and public notes using the same syntax
  • ox-hugo is really easy to use, especially since I am using Doom Emacs and it can be enabled as an org-mode flag using (org +hugo)

so, with that said, let’s get into the fun stuff !

Starting a new hugo blog

go ahead and install hugo, either from your distro’s package manager or using npm (npm -g hugo-cli). for me, I’ll be using pacman

sudo pacman -S hugo

next, initialize your hugo project, using their cli

hugo new site project-name

this will create a directory called project-name that contains the project starter next, you need to pick a theme for your blog, you can find some community-made themes in Hugo’s Website

once you’ve picked a theme that you like, just clone the github repo into your Hugo’s theme directory (project-name/themes)

git clone https://github.com/rhazdon/hugo-theme-hello-friend-ng.git themes/hello-friend-ng

finally update your config.toml to apply the theme that you’ve just downloaded, and while you’re at it, you might as well update the blog’s metadata (title, description, language, etc..)

baseurl      = "/"
title        = "My Blog"
languageCode = "en-us"
theme        = "theme-name"
...

you can now visit your site by running this command and opening localhost on port 1313

[youssef@tux ~/repos/hugo-blog]$ hugo server -D
Start building sites …
hugo v0.88.1+extended linux/amd64 BuildDate=unknown

                   | EN
-------------------+-----
  Pages            | 16
  Paginator pages  |  0
  Non-page files   |  0
  Static files     | 19
  Processed images |  0
  Aliases          |  4
  Sitemaps         |  1
  Cleaned          |  0

Built in 586 ms
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at //localhost:1313/ (bind address 127.0.0.1)

Installing and configuring ox-hugo

ox-hugo is the package we are going to use to transform our org file(s) to markdown which then will be parsed by hugo

Installing ox-hugo

Vanilla emacs

you can install ox-hugo using use-package

(use-package ox-hugo
  :ensure t            ;Auto-install the package from Melpa (optional)
  :after ox)

Doom emacs

You can enable hugo by just adding the hugo flag to the org module in your init.el so it looks something like this (org +hugo)

Integrating ox-hugo into our hugo blog

there are two ways to use ox-hugo:

  1. all the posts in one org file, one post per-subtree (Recommended)
  2. one post per org file

you may be more familiar with the second option but having all of the posts in one file has its benefits too

  • makes the meta-data management for Hugo front-matter pretty effortless.
  • you can use org mode’s Tag Inheritance feature

so now that is out of the way, start by creating an org-file in your project’s root, you can call it whatever you want. next, add a local variable at the top of the page and call it HUGO_BASE_DIR and set this to the absolute path to your hugo project, for me that looks something like this

#+HUGO_BASE_DIR: ~/repos/hugo-blog

Write your first post !

to make a new post you just need to add a new top-level heading to the org-file that we created, but you also need a bit of metadata. here is an example post:

* Blog Post name
:properties:
:export_file_name: blog-post-name-in-url
:export_description: my cool post
:export_date: 2021-10-18
:export_author: your name
:end:
post's content !

finally to export the file to markdown you can run the org-hugo-export-wim-to-md function to export the blogpost to markdown and place it in the content folder in your hugo project on doom emacs, you can also use the keybinding SPC m e H H to do the same thing now if you open localhost:1313 (make sure the hugo server is still running) you will see your newly created blog post show up !

And that’s about it, I hope you’ve found this helpful, if you made you blog using this guide, tweet me over at @spcbfr and I’ll make sure to check it out !