Using Org Mode in Hugo

I'm learning org-mode and I don't really know what I'm doing, but this is how I'm trying out writing hugo posts with it. I'm used to markdown, so this is a what's different post.

Some minor org-mode tweaks

For some reason when org-mode starts it doesn't softwrap the paragragh text. I like to have it soft-wrapped so everything is on the screen if it's not collapsed. Also having some nice indentation makes things visually cleaner, so add this snippet to your ~/.emacs to have these turned on by default.

1
2
3
(with-eval-after-load 'org       
  (setq org-startup-indented t) ; Enable `org-indent-mode' by default
  (add-hook 'org-mode-hook #'visual-line-mode))

Integrations

Hugo has .org file support natively, which is what I'll be using. There are other options out there, ox-hugo being the big one. This will let you write in org and then export into a .md file that hugo understands and gives you more control of the output. Check that out if you have additional needs that are required.

Front matter

While Hugo has front matter, you can easily translate that into org-mode document properties. For example, this is what is on the top of this file:

#+title: Using Org Mode in Hugo
#+subtitle: emacs everywhere
#+date: 2019-08-02
#+tags[]: howto, emacs, hugo

Which maps pretty directly to the toml front matter.

Document navigation

`C-c C-n`	Move to the next heading
`C-c C-p`	Move to the previous heading
`TAB`	on a heading will collapse/expand

Formatting

Emphasis

Style	Code
bold	`bold`
italics	`/italics/`
`literal`	`=literal=`
link	`[[https://willschenk.com][link]]`

Blocks

Code can be formatted in blocks like this:

#+BEGIN_SRC ruby

#+END_SRC

Where ruby is the language type.

You can auto fill out that structure with <sTAB at the beginning of a line.

CSS

For blocks you can set specifc classes to be added to the html, so for example

#+CAPTION: This is my caption
#+ATTR_HTML: :class table table-striped table-dark
| Key | Value                |
| 1,2 | Jim Butters was here |

Will render like this (since this css is based off of bootstrap)

Key	Value
1,2	Jim Butters was here

This is my caption

I don't have a good css style for figures or captions so it's just lingering there at the bottom right now

Embedding images

HTML in org-mode is automatically escaped which means that you'll need to write a small shortcode to embed things. Otherwise you'll get this:

There are a lot of short-codes built in that work directly for example the tweet code:

The Colonial motel in Brattleboro is the best motel in the world. $60/night, 2 full sized pools in the spa with a great hot tub. Love this place.
— Will Schenk (@wschenk) August 2, 2019

Here is my /layouts/shortcodes/img.html short code that lets do you a little image processing on images in the same page:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{{ $imageName := .Get "img" }}
{{ $images := .Page.Resources.Match $imageName }}
{{ $image := index $images 0 }}
{{ $fill := .Get "fill" }}
{{ if $fill }}{{ $image = $image.Fill $fill }}{{ end }}
{{ $fit := .Get "fit" }}
{{ if $fit }}{{ $image = $image.Fit $fit }}{{ end }}
{{ $class := .Get "class" }}
{{ $style := .Get "style" }}
{{ print "<img class='" $class "' style='" $style "' src='" $image.RelPermalink "'>" | markdownify}}

This is the output of <img img="primo.jpg" fit="200x200 smart">

Conclusion

I barely understand how org-mode works but it's changing my life. I want to be able to write everything in this, so while there are a few things still need to be worked out I think I'll be able to write a lot more often.

Being able to collapse the headings using TAB and navigate through sections using C-c C-p and C-c C-n makes nimble the process of organizing tasks. Fully recommend!

References

Hugo Website
go-org hugo uses this to parse your files
https://ox-hugo.scripter.co/
https://gohugo.io/content-management/shortcodes/#readout