Setting Emacs Variables in Hugo Markdown

If you want to set Emacs File Variables in your Hugo markdown files but not have the Emacs variables visible in your rendered content you have a couple of options:

Option 1 – use an HTML comment

Include the file variables in an HTML comment – that will be stripped out, at least if you are using the default Goldmark renderer. That looks like this:

<!-- 
Local Variables:
mode: markdown-mode
whitespace-line-column: 100
End:
-->

This will be replaced with ‘<– Raw HTML omitted –>’ in the rendered HTML, but won’t produce any user-visible display artifacts.

Option 2 – use a shortcode

Build a shortcode that doesn’t render any content. This is what I ended up doing, because I didn’t want to rely on a side effect of the markdown renderer that could, conceivably, change in the future. To do this, create the shortcode in the layouts/shortcodes/ directory for your site:

{{- if .Inner }}{{ end -}}

Note that this shortcode does need to reference .Inner or else Hugo will error out. That’s the reason for the seemingly pointless if .Inner block.

You can name the file whatever you want, but the name will be how you invoke the shortcode. I named mine comment.html. Now, I can include this at the bottom of my markdown to set my Emacs state:

{{ <comment> }}
Local Variables:
mode: markdown-mode
whitespace-line-column: 100
End:
{{ </comment> }}

…But Don’t Mess with the Front Matter Block

There is no way (at least that I could find) to set file variables on the first line of the file. Including any lines prior to the front matter block will cause Hugo to error out. Interestingly enough, if you try to set the Emacs variables like this:

--- -*- Mode: markdown-mode; whitepace-line-column: 100 -*-
title: "My Post"
date: 2024-01-01
...
---

Hugo won’t error out, but front matter from any post that contains the extraneous characters will be inaccessible to Hugo render hooks. So, for instance, you’ll see posts rendered in a random order (because it can’t retrieve the dates from the front matter blocks), or posts will be rendered without titles, tags, etc.