Ox Hugo for the Orgconfig

What?
I’m combining all my orgconfig files into one, and then using
ox-hugo
to generate Markdown files for my Hugo site.
Why?
Hugo renders Org files just fine, but I wanted my config to be a bit more
tightly integrated. ox-hugo
works well as both plain old Org and as an
intermediary that exports Hugo content. A single Org file can become as many
Hugo pages as I want.
Getting it to work
This week my favorite Emacs flavor is Doom Emacs. Their org
module supports ox-hugo
as an option, so enabling that option in
my init should do the trick — after a doom sync
of course.
(doom!
⋮
:lang
(org +hugo))
Off in the depths of my ~/org/
folder, I create a new config.org
.
#+title: My Orgconfig
#+hugo_base_dir: ~/Sites/random-geekery-blog/
#+hugo_section: config
Everything here will end up going in the config
section of my site, under
~/Sites/random-geekery-blog/content/config
.
Each top-level section will be a page in /config/
.
I show which page in the subtree’s :properties:
.
+ Emacs config
:properties:
:export_description: Be kinda weird if I didn't manage that one in Org, yes?
:export_file_name: emacs
:export_hugo_weight: 5
:end:
ox-hugo
automatically converts the export
properties to Hugo front
matter. :export_file_name:
of emacs
maps out to a generated file
emacs/index.md
under content/config/
.
Since I’m showing off Babel’s ability to tangle, I want to show the
tangle references. :noweb no-export
tells Babel to tangle when evaluating
the block, but not when exporting.
#+name: zsh/base-variables
#+begin_src text :noweb no-export
<<zsh/set-base-path>>
<<zsh/define-editor>>
<<zsh/clicolor>>
<<zsh/add-home-bin>>
#+end_src
And — yeah. I still haven’t figured out a nice way to highlight those tangle bits, so for the moment I default to calling my mostly-tangled blocks “text”.
I also create a subtree for the section _index.md
.
+ My personal orgconfig
:properties:
:export_file_name: _index
:end:
#+begin_note
This is my live config, written as an [[https://orgmode.org/][Org]] file and integrated with my site with [[https://ox-hugo.scripter.co/][=ox-hugo=]].
⋮
Now my config section summary is part of the config org file. I find this aesthetically pleasing.
The rest is implementation details
This whole process is fiddly. Org mode. Literate config. Hugo. ox-hugo
.
That makes the whole thing fiddly^4 or something. But these quick notes
covered things that got in my way while gluing the whole thing together. If
you want to try it out, at least some of the fiddliness should be clearer.