Blogs with Hugo and org-mode!
searchforzero
Table of Contents
EDIT: My blog is no longer published with Hugo, but of course I still use org. I've switched to org's org-publish feature. org-publish is less featureful, but I wanted my site to be simpler anyway. However this post is still relevant for using ox-hugo to export org files to Hugo compatible markdown. In fact the underlying org file didn't need to change except for removing some properties and changing the path to some image resources. See how I currently publish my site with org-publish in Blogs with org-publish.
This blog post was written in emacs' org-mode alongside Hugo!
* Blogs with Hugo and org-mode! CLOSED: <2020-01-31 Fri> :PROPERTIES: :EXPORT_FILE_NAME: file_name :END: This blog post was written in emacs' org-mode alongside Hugo!
By making use of org-mode's org-export-dispatch functionality the above org code can be exported to Hugo compatible markdown. All you need is the wonderful ox-hugo emacs package.
You might be wondering "why would I use org-mode to produce markdown, isn't it easy enough to just write the markdown?" to which I say, yes, Hugo markdown is very easy to write and if you don't use emacs–and are happy that way–then I won't try to convince you to make the switch (though I will say that org-mode, along with magit, are the sole reasons why I took up emacs as a vim user). But if you are an emacs user then you likely already know the power of org-mode and are probably looking to maximize your time there. But don't take my word for it, the ox-hugo site has a page entitled Why ox-hugo? which was more than convincing enough for me.
Mainly, all the nice features of editing text in org-mode now carry over to your blogging workflow, how nice! Another plus (for some folk) is that you can keep all your blog posts in one org file as sub-trees. This makes navigating, searching, and editing your site a breeze.
I'll briefly showcase a few of my favourite features so far:
Images
Of course you have image support with the standard org-mode syntax:
#+CAPTION: Don't worry, I'm no Linux elitist, just a Windows hater. ~/images/inevitable.jpg
Which produces this charming depiction of the future:
Figure 1: Don't worry, I'm no Linux elitist, just a Windows hater.
Tables
The universally loved org tables are handled by ox-hugo as well:
| Nickname | Height | Favourite Food | |----------+--------+----------------| | Condor | 181 | pizza | | Speed | 184 | eggs | | Meat | 188 | vegetables | | Darco | 176 | pizza | | Apple | 186 | chocolate eggs |
| Nickname | Height | Favourite Food |
|---|---|---|
| Condor | 181 | pizza |
| Speed | 184 | eggs |
| Meat | 188 | vegetables |
| Darco | 176 | pizza |
| Apple | 186 | chocolate eggs |
The code here only makes sense if you've used org-tables, otherwise it looks horrid to type. You can trust me that they're great (and if you don't, look here).
\(\LaTeX\) (my favourite 💖)
With a little extra configuration (namely, the addition of MathJax into your Hugo theme) you can even export the \(\LaTeX\) code that is supported in org-mode, which is much nicer than writing pure \(\LaTeX\) in most cases. Have a gander:
\begin{equation} \frac{\sum_{i=1}^{n}{2i^5}}{\lvert \frac{1}{\sqrt{n}} \rvert} \text{, where } n = 19 \end{equation}
Ah I really love org-mode… If only I knew it existed during math classes!
Summary
I am just scratching the surface with this workflow but I can already foresee it being very pleasant in comparison to managing a hugo project with raw markdown. Not that Hugo and other static site generators aren't great already–because they are–it's just that org-mode makes everything just that tad bit better.