Using Org Mode in Hugo

emacs everywhere

Published August 2, 2019 #howto, #emacs, #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.

(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-07-26
#+tags[]: howto, emacs, hugo
#+draft: true

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:

<img src="primo.jpg"/>

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

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

{{ $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" }}
{{ print "<img class='" $class "' 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

Read next

See also

Splitting Git Repos and Work Directories

all the fun things git can do

I found a tutorial on how to manage your dotfiles, that works by splitting up the git repository (normally the .git directory) from the work directory. Since I have a lot of code that I put in my tutorials, I adapted the technique to have individual article directories mirrored in their own github repository. Repositories and Work Directories The normal usage of git is to type git clone <remote> to get a copy of the local directory, mess with stuff, and then add and commit your changes.

Read more

Easy scraping with httpie and jq

Pulling my GitHub starred repositories into Hugo

I recently saw a tweet mentioning the combination of using HTTPie (a command line HTTP client), jq (a lightweight and flexible command-line JSON processor) and Gron (Make JSON greppable!) was “all you needed to build a scraper.” Lets see if that’s true.

Read more

Automating hugo builds using CircleCI

Let someone else run your build server

Here's a simple CircleCI configuration to pull down the latest version of your hugo site on GitHub commits, build it, and then push it to github pages.

Read more