Implementing gemtext support for Hugo

October 19, 2021

Regarding the use of static site generators in gemspace, I've noticed people tend to write content in Markdown to then programatically convert it to gemtext. These tools were very much designed for use in the HTML-centric web, and so Markdown is an excellent tool to generate semantic HTML without dealing with the nuts and bolts of it. But this doesn't really apply to gemtext, does it? It always struck me as very odd, since gemtext is practically a subset of Markdown, and you lose a lot going from the former to the latter. What always made sense to me was opposite; writing content in gemtext first. This way, you can serve your capsule content with only very basic templating, as you're already dealing in its native format. And if also have to output HTML, then it's not hard to write a converter from gemtext to HTML just as there is for Markdown! And that's precisely what I did for Hugo.

The Hugo website

The "gemtext" branch of my personal clone of its source code

A README for the features I added

The way the converter works is described in the README, but I'll mirror it here:

A "p" element is generated for any sequence of non-empty lines, where "br" is used to separate them

A "figure" element is generated for any block of preformatted lines, where the actual performatted content is inside a "pre" tag, and the alt text, if present, is inside a "figcaption"

A "blockquote" element is generated for any sequence of quote lines; "br" is used to separate them just like text lines

"h1", "h2" and "h3" correspond to heading lines

Any sequence of non-empty link lines is output as a "ul" element with the "links" class, where each item is an "a" element prepended by a "li" tag

Any sequence of non-empty unordered list lines is output as a "ul" element with the "items" class, where each item is text prepended by a "li" tag

If you'd like to test it out, just build Hugo like the official instructions say (using the "gemtext" branch of my personal clone). You should then be able to use gmi files just like you'd use md files. And if you'd like to try converting gemtext to HTML through this method without bothering to set up a whole Hugo environment, you can run this submodule as an executable! It will read from standard input and write to standard output.

The standalone converter

Here's the HTTP mirror of this very page, so you can see the converter in action.

https://tilde.team/~zerica/gemlog/hugo-gemtext/

And here is some formatted gemtext content!

Unordered list below:

item one

item two

item three

> And this... is a blockquote!

> Line two of the blockquote.

Hopefully this can be of use to you!