💾 Archived View for tdem.in › post › gemini-with-gmnhg.gmi captured on 2022-06-03 at 22:53:52. Gemini links have been rewritten to link to archived content

View Raw

More Information

-=-=-=-=-=-=-

Back to blog

Running a Gemini site with gmnhg and Hugo

2020-11-26 03:45

This site has recently got its Gemini version thanks to the tool I wrote, gmnhg, available at `gemini://tdem.in`. The tool has already met its first milestone, v0.1.0, so this is likely a good moment to recap on the whole idea of working in a Hugo site into the Geminispace.

Gemini

gmnhg

v0.1.0

Markdown, even though being quite complex as the CommonMark specification shows (the CommonMark spec was originally designed to clean up the ambiguities of the original 2004 spec that resulted in quirky behaviour across various renderers), is simple enough to be converted to reasonable Gemini text (named Gemtext here) if you only use a subset of it. This means source Markdown can be converted to native Gemtext content just fine as long as some editor discretion is used when running a Gemini-friendly blog.

CommonMark

As most simple Markdown formatting can be converted to Gemtext using either the tools Gemtext provides or just left unmodified as plain text, it can be used as a Gemtext source, with following exceptions:

tools Gemtext provides

Testing your Markdown is made simple with `md2gmn`, another tool I wrote that is distributed alongside `gmnhg` that only renders Markdown text to Gemtext, to see if any of your Markdown fails to properly render to the medium Gemini provides.

`gmnhg`, on the other hand, does the uplifting of processing your Hugo content files into an output dir suitable for being served by a Gemini server such as satellite while also taking care of generating index pages and such. The resulting Gemtext is then passed to Go's `text/template`, and you can customize the templates by adding the ones relevant to you to the `gmnhg/` dir. The algorithm is already summarized quite well in its godoc page, so there's no real point in going over it again.

satellite

godoc page

Markdown site converted to Gemini, index page opened in Amfora

`gmnhg` respects stuff you'd probably expect a Hugo companion to obey: it takes care about copying static files to the output dir, it won't render draft posts, etc; yet, `gmnhg` at this time doesn't support much of the rich functionality Hugo provides to your blog (taxonomies, etc), but, to be fair, a lot of it is complex enough to not fit well in a simple Gemini blog. Yet, I am completely open to patches that implement certain Hugo stuff that works fine with Gemini.

This site's sources can serve as a reference for those who need an example on how to use gmnhg to serve their site to Gemini.

serve as a reference

Gemini is too escapist / privacy-focused in the tools it provides (and I still think mandatory TLS in a braindead-simple protocol is a dumb idea), but no one has come up with a decent enough of a Web replacement, so I guess this blog will stay available on Gemini (and having coded a few tools for its support counts for enough effort to make leaving Gemini retrospectively costly). This new medium is simple and hacker-friendly, so I advise you to explore it as well!