Hugo & org-mode

Both of my sites are written in Hugo as it is unbelievably fast in terms of building websites. It can deploy thousands of .md files, one per page, within a second, meaning I can almost write markdown documents and check the generated html page (and a complete version of the entire website) almost simultaneously. This is a critical feature to me since I constantly change blog entries and edit site parameters as a total newbie.

A year ago, when I was using Sublime and BBedit, markdown formats worked just great, straight-forward and easy-to-remember syntax. With tree structured sidebar integrated in both editors, jumping between folders and files were effortlessly. A year after, though, I have dig into another rabbit hole 🐇 (Emacs) and way too deep. Getting used to org-mode also means being awkward with other text editors, and worse, with other file types. I find it a bit painful writing my last post with markdown, even with a powerful Emacs markdown-mode.

(A ton of guides on how to build a site with Hugo are available a google away. For this entry I won't touch on this subject.) The solution I found to integrating org-mode and Hugo is the Emacs-easy-hugo package. I noticed more discussions and posts on an alternative option with ox-hugo exporter but less on easy-hugo, so sharing my two cents about the latter in this entry. Incredibly easy to set up if you already have a functioning Hugo site running.

Emacs-easy-hugo

Several advantages of the easy-hugo package:

• easy to install via melpa
• easy to configure
• flexible and abundant org-mode features

I will start with the last advantage. For example, the literal programming integration allowed by org-babel. When I want to export a tree view for my blog folder to better demonstrate the configuration, there is no need to open terminal, execute the command, and paste the result back into org-mode. In stead, I can use the code block to export the result directly.

Org-babel

The original code block used in org-mode is:

#+begin_src shell
cd ~/hugo/swnsa
tree -v --charset utf-8
#+end_src

And the output automatically inserted in the org-mode file is shown as:

I cannot elaborate enough how deeply intrigued I am by this brilliance.

Easy-hugo easy-configuration

Based on the above folder structure, below is the configuration added in my init file. In fact it is for two sites, which demonstrate another nice feature of easy-hugo, making managing and deploying multiple sites a breeze.

(setq easy-hugo-root "~/hugo/")
(setq easy-hugo-sshdomain "mini")

(setq easy-hugo-bloglist
	;; blog
      '(((easy-hugo-basedir . "~/hugo/swnsa/")
	 (easy-hugo-url . "http://ying-ish.com")
	 (easy-hugo-postdir "content/essay/"))
	;; blog2 for photos
	  ((easy-hugo-basedir . "~/hugo/mini/")
	   (easy-hugo-url . "https://mini.ying-ish.com")
	   (easy-hugo-postdir "content/photo/"))))

(setq easy-hugo-server-flags "-D")

Single blog site is even easier to set up following the GitHub readme.

Write and deploy

To write in org-mode, simply activate easy-hugo mode, start a new post with .org extension. That's all you need to do. At any stage, easy-hugo can convert org format to markdown nicely. (It is not actually convert the format of the original org file, but more like a filter or an temporary exporter.)

This site is powered by Netlify with auto-deploy from the GitHub repository . I highly recommend this setting as, first, it is free, and second, Netlify is really fast. Without Netlify, I may need to wait for 2-3 minutes for GitHub page to deploy but with Netlify it never cost more than 30 seconds.

I have a script to automate the git update which only cost 2 key strokes. But with Emacs-magit it is also super fast.

Save, commit, and done.