hmbrg.xyz

Entering The Gemini Network

Table Of Contents:
A week or so ago I decided to host my internet presence also at the Gemini network but before that I had to select the tool-set to realize this idea. After testing some solutions I settled down with GSSG ̚ as the static site generator and Satellite ̚ for serveing my capsule.

Gemini’s markup language Gemtext

The content is entered via the marku-up language Gemtext which similar to Markdown but much more rudimentary and condensed down to the following set of styling features:

Headings

There are only three levels of headings which are used the same way as in markdown:

1
2
3
# Heading
## Sub-heading
### Sub-subheading

Lists

Only one kind of list is available in Gemtext:

1
* list without nesting capabilities

Quotes

1
> Quotes

Every link starts with =>, followed by optional whitespace (space/tab), followed by the URL (any protocol is possible), followed by optional whitespace and finally optional followed by a label with no character limit.

1
2
3
4
5
=> /path/to/content-files.gmi Some interesting stuff
=> /path/to/image-file.png My Hackfresse
=> https://hmbrg.xyz My website
=> mailto:me@example.com drop me a line
=> xmpp:me@jabber.com

Something like: I found the following => gemini://private-gemlog.com which is a perfect source of knowledge!

Doesn’t work!

Preformated text

This styling feature is somewhat the equivalent to / of HTML and is generated by content blocks enclosed in three backticks (```) before and after the corresponding content. The leading/trailing three backticks has to be at the beginning of a line! The first three tell the client to toggle into preformated text mode and the second set toggles back to ordinary rendering mode.

Example with and without backticks:

1
2
3
4
5
6
Before this line there are three backticks!
This
		is
			preformated
						  	 text
After this line follow three backticks!
1
2
3
4
5
6
Before this line the three backticks are missing!
This
is
preformated
text
After this line the three backticks are missing, too!

As you can see in the second example the leading whitespaces were removed.

Installing GSSG

First the corresponding repository has to be clone by running:

git clone https://git.sr.ht/~gsthnz/gssg

Next navigate into the directory where GSSG was clone to: cd gssg

In that directory execute the following two commans:

1
2
make
(sudo) make install

Before starting to use GSSG a directory which holds all the necessary files need to be initialized via:

gssg -init my-gemini-capsule

Which will create the following structure:

1
2
3
4
5
6
7
8
my-gemini-capsule
├── config.toml
├── content
│   └── index.gmi
└── templates
    ├── atom.xml
    ├── index.gmi
    └── page.gmi

The default template expects posts within the content/posts folder, and it will display them on the index.gmi page ordered by date.

At this point, we have a working gssg installation. To generate the site, simply run:

gssg

Dates

Dates will be populated on the page information via the filename or the contents of the file.

If the filename has a YYYY-MM-DD string, that will be counted as date, if not, gssg will search in the file contents for the first entry of YYYY-MM-DD and use that as date. My personal preference is to add the date at the beginning of the filename.

Next the file config.toml needs some love as the following lines needs to be change to personal preference:

1
2
3
4
5
6
7
title = "Title of the Gemini capsule" # Title of the gemlog
url = "example.com" # URL of the gemlog
source_dir = "content" # Directory of the source files
dest_dir = "public" # Directory of the generated files
template_dir = "templates" # Directory for the templates
feed_title = "Gemlog ATOM Feed" # Atom Feed name
feed_path = "posts/" # Directory on source_dir to search for articles for the feed

Templates

There are three available templates at the moment, page.gmi, index.gmi and atom.xml

Page template variables

1
2
3
4
5
Content (Raw content of the file, this does not strip the title)
Title (Title of the page, will be populated from the first heading found in the page)
Date (Date of the page, will search for YYYY-MM-DD on the filename or in the content)
Permalink
Config.URL (Main URL of the page)

Index template variables

Same as page Children (Map of children posts with the key as the relative directory and the value as a slice of non index.gmi Posts)

Atom feed variables

1
2
3
4
5
Title (feed_title from config.toml)
Path (feed_path from config.toml)
URL (url from config.toml)
Updated (The time this file was last generated)
Entries (Array of Pages found on feed_path)

Installing Satellite

Before installing Satellite the following dependencies needs to be satisfied:

1
2
build-essentials
golang

Cloning the Git repository

1
git clone https://git.sr.ht/~gsthnz/satellite

Compiling Satellite

1
2
make
(sudo) make install

Launching at reboot

To make sure Satellite will be started if the server gets rebooted add the following line to crontab:

Configuring Satellite

Configuration is done within /etc/satellite.toml. To do so first copy /usr/local/share/satellite/satellite.toml to /etc/satellite.toml. Afterwards edit it’s contents to fit needs.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Address to listen to requests (default: 0.0.0.0:1965)
listen = "0.0.0.0"

[tls]
# Directory to save certificates
directory = "/var/lib/gemini/certs"

# Multiple domains can be set within the [[domain]] section
[[domain]]
name = "example.com"
root = "/var/www/example.com/gemini"

First execution

To launch Satellite in the background simply run: /path/to/satellite &

That’s it now the content within /var/www/example.com/gemini is available through the Gemini network.


Tags: Gemini, gemtext, GSSG, Satellite

This page was last updated on: 28. September 2021