Stephen Lindberg

Product Designer @ Iterable

14 February 2021

Authoring a Gemini Capsule with Hugo

I’ve been exploring Gemini recently and I love the simplicity. Ideally one can author a Gemini “capsule” with just a text editor, but creating something slightly more complex such as a tagging system, universal navigation, or a simple RSS feed becomes tedious. One of my favorite softwares is Hugo, which is very configurable, so I decided to figure out a setup for generating a Gemini capsule. Here’s the gist:

Configure Hugo

In Hugo’s config.toml define the text/gemini media type and assign it as the main output type for all pages:

    suffixes = ["gmi"]

    name = "gemini"
    mediaType = "text/gemini"
    basename = "index"
    isPlainText = true
    protocol = "gemini://"

  home = ["gemini", "RSS"]
  page = ["gemini"]
  section = ["gemini", "RSS"]
  taxonomy = ["gemini"]
  term = ["gemini", "RSS"]

Define a handful of templates

Templates will use the gmi extension.

Create layouts/_default/list.gmi for section pages:

# {{ .Title }}
{{ .RawContent }}

Pages in this section:
{{ range .Pages }}
=> {{ .RelPermalink }} {{ .Date.Format "2006-01-02" }} {{ .Title }}
{{- end -}}

Create layouts/_default/single.gmi for section pages:

# {{ .Title }}
{{ .RawContent }}

And start writing!

Pages are created in the usual way: hugo new my-page-title/ with the appropriate front matter.

From here you can easily create reusable partials such as navigation.gmi, a basic RSS feed index.xml, and pages to enumerate your taxonomies with terms.gmi. You could of course do something more sophisticated, but I found this setup to strike a good balance between the fun of hand-authoring pages and the ease of automatically updating things like navigation and RSS.