home blog tags about

From lektor to gemlog

written by Robin Schubert on 2021-02-22 | Tags: free-software


I recently get really pissed quite often when I browse the web; I'm nuked with ads and pop-ups or - should I dare to use an adblocker - will not be able to see the content I was looking for at all. With the GDPR in place, living in Europe also reveals the incredible amount of Cookies used for profiling and tracking my browsing behavior. I'm being tracked everywhere, always.

Sure, I can opt-out. That's what they say. And it's a bad joke.

I cannot opt-out of what is called "essential to make the site run", which is obviously a whole lot. Technically it's forbidden to make the opt-out process harder then the opt-in, but I have never seen a single of these modal dialogs that would have offered me an "opt-out of everything" button that was just as easy to find as the "I agree to everything" button. Now even if I opt-out of everything, sites hide their "legitimate interest" settings on another page where I often need to manually de-select zillion items.

That's not the web I learned to love and I want to use as a major source of daily information.

I also recently learned about a new internet protocol that aims to make things different than HTTP/S, called gemini. If you're familiar with the gopher protocol, which has been around for some time now, you can put gemini somewhere between gopher and HTTP/S. By intention it does not much. It will let you display text, basically, that you type in a markdown-like syntax called gemtext. The function set is very limited on purpose, so content counts. It does not support images or inline links, but three levels of headings and code blocks. gemini does also TLS by default and explicitly welcomes self-signed certificates.

Hosting a Gemlog

To serve a gemlog, a server is needed; since TLS is a requirement, it's not sufficient to just serve the file structure. There are a couple of lightweight servers available, I'm using gemserv here, which I found fairly easy to compile and configure.

Generating a Certificate

I use openssl to generate a private key and a certificate signing request (CSR):

openssl req -new -newkey rsa:4096 -nodes \
  -keyout private_key.txt \
  -out csr.txt \
  -subj "/CN=gemini.schubisu.de"

This will generate an X.509 certificate signing request with a new RSA 4096 bit key. The nodes option will skip encryption of the key. You can put more information in the subject name, it's important to have the CN right, however, to let it match your domain.

With the CSR we can generate the certificate:

openssl x509 -req -sha256 \
  -days 365 \
  -in csr.txt \
  -signkey private_key.txt \
  -out certificate.txt \
  -extensions req_ext

The private_key.txt and certificate.txt will need to be on our server.

Configure gemserv

If available in your packet manager, install gemserv from there, or clone the repository and follow the build instructions. The configuration can be as simple as the following config.toml file:

port = 1965
host = ""

hostname = "gemini.schubisu.de"
key = "/path/to/private_key.txt"
cert = "/path/to/certificate.txt"
dir = "/path/to/content"

and simply run

/path/to/gemserv config.toml

For local testing you don't even need to have a registered domain, just add a line like this to your /etc/hosts file:    gemini.schubisu.de    localhost

Converting my lektor blog to gemtext

I write my blog with a lightweight CMS for static websites written in python, called lektor. I always liked about lektor that it's file structure mirrors the resulting web page. Every page I write is represented by a folder that contains at least one content.lr file which consists of a bit yaml and markdown.

This is very much like what gemini expects, which will either show you the subfolders of a directory, or - if present - renders the index.gmi (or index.gemini) file.

I started by renaming all contents.lr files to index.gemini to get the quickest possible working gemlog and an initial idea of what work lies ahead of me. It works, of course, but there is still plenty of room for improvement. What needs to be adjusted are

I decided to write a small python script, to use lektor's API to access all meta information and contents. I also reviewed all my blog posts to bring the links into a standardized format:

 # inline links:
 [some text][identifyer:my_link_name]

 # and at the bottom of the document:
 [identifyer:my_link_name]: https://...

The script will convert that into valid gemini links that are numerically indexed inline when rendered:

# inline links:
some text[1]

# and just below the paragraph:
[1] my_link_name [some text]

I also edited a few minor things in my contents.lr to make the markdown comply with gemtext:

I've uploaded the script to convert the blog here. It's pretty much tailored to my needs. However, it may be useful if you happen to run into the same or similar idea :)

For what it's worth, I can now simply run my conversion script, rsync the files to my gemini server and that's it.

You can grab a gemini browser and checkout the results of my conversion at gemini://gemini.schubisu.de

Creative Commons License