howto

Using Org Mode in Hugo

emacs everywhere

tags
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.

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-nMove to the next heading
C-c C-pMove to the previous heading
TABon a heading will collapse/expand

Formatting

Emphasis

StyleCode
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)

KeyValue
1,2Jim 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:

 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!

Previously

howto

Installing guix on IntelNUC

using the hardware you have, even if we are nonfree

tags
freesoftware
guix
docker

Next

howto

Setting up an IPFS Node

using docker-compose and certbot

tags
ipfs
docker
docker-compose
certbot