gmnhg

Documentation

Overview

gmnhg converts Hugo content files to a Gemini site. This program is to be started in the top level directory of a Hugo site (the one containing config.toml, config.json, or config.yaml).

gmngh will read layout template files (with .gotmpl extension) and then apply them to content files ending with .md by the following algorithm (layout file names are relative to gmnhg/):

1. If the .md file specifies its own layout, the relevant layout file is applied. If not, the default template is applied (single). If the layout file does not exist, the file is skipped. Draft posts are not rendered. _index.md files are also skipped.

2. For every top-level content directory an index.gmi is generated, the corresponding template is taken from top/{directory_name}.gotmpl. Its content is taken from _index.gmi.md in that dir. If there's no matching template or no _index.gmi.md, the index won't be rendered.

Templates for subdirectories are placed in subfolders under top/. For example, a template for an index at series/first/_index.gmi.md should be placed at top/series/first.gotmpl.

3. The very top index.gmi is generated from index.gotmpl and top-level _index.gmi.

The program will then copy static files from static/ directory to the output dir. Page resources (non-Markdown files) will also be copied from the content/ directory as-is, without further modification.

Templates are passed the following data:

1. Single pages are given .Post, which contains the entire post rendered, .Metadata, which contains the metadata crawled from it (see Metadata in internal/gmnhg/post.go), and .Link, which contains the filename relative to content dir (with .md replaced with .gmi).

2. Directory index pages, including the top-level index, are passed .Posts, which is a slice over post metadata crawled (see Metadata in internal/gmnhg/post.go), .Dirname, which is the directory name relative to the content dir, .Link, which contains the index filename relative to the content dir (with .md replaced with .gmi), .Content, which is rendered from directory's _index.gmi.md, and .Site, which contains site-level configuration data loaded from the Hugo site's config.toml, config.yaml, or config.json.

The following keys are available in the .Site map, listed with their associated Hugo configuration key: .BaseURL (baseUrl), .GmnhgBaseURL, (gmnhg.baseUrl), .Title (title), .GmnhgTitle (gmnhg.title), .Copyright (copyright), and .LanguageCode (languageCode).

Directory indices are passed all posts from subdirectories (branch and leaf bundles), with the exception of leaf resource pages. This allows for roll-up indices.

3. RSS templates receive the same data as directory index pages, but the filename provided by .Link is rss.xml instead of index.gmi.

This program provides some extra template functions on top of sort:

* sort, which sorts slices of int, float64, strings, and anything implementing sort.Interface (which includes slices of posts), returning a new, sorted slice.

* sortRev, which works like sort, but sorts in reverse order.

* sortPosts, which is an alias to sortRev preserved for backwards compatilibity.

Template functions from sprig are also available (https://github.com/Masterminds/sprig); see the sprig documentation for more details.

RSS will be generated as rss.xml for the root directory and all branch directories. Site title and other RSS metadata will be loaded from the Hugo configuration file (config.toml, config.yaml, or config.json).

gmnhg provides a way to override these attributes by defining a "gmnhg" section in the configuration file and nesting the attributes to override underneath this section. Presently you can override both "baseUrl" and "title" in this manner. It is recommended to override at least "baseUrl" unless your site uses a protocol-relative base URL (beginning with a double slash instead of https://).

RSS templates can be overriden by defining a template in one of several places:

* Site-wide: gmnhg/_default/rss.gotmpl

* Site root: gmnhg/rss.gotmpl

* Directories: gmnhg/rss/dirname.gotmpl for a directory "/dirname" or gmnhg/rss/dirname/subdir.gotmpl for "/dirname/subdir"

One might want to ignore _index.gmi.md files with the following Hugo config option in config.toml:

ignoreFiles = [ "_index\\.gmi\\.md$" ]