When I first started working on this website, I thought we might host it on Gemini[^]. Gemini is a minimal internet protocol as well as a text-based format for pages.
The format for gemini pages is really simple. Plain text shows up as plain text. Otherwise you have headers, lists, quotes, block quotes, and links. Here are examples of how they look in gemini:
# Header ## Subheader ### Nested subheader => example.com Link To Example Website * List element * Second list element * ... > This is a quote. ``` This is a block quote. Note: normally there's no space before the ```. ```
Examining the first 3 characters is always enough to determine what kind of line it is, which makes parsing extremely easy. And it's all just normal plain text.
The simplicity is nice. Even though we never ended up putting the website on gemini, even now every page is generated from gemini using a home-grown gemini to html converter, with just a bit of css to make the pages look nice and clean.
An interesting aspect of gemini is that every link must be on its own line. This results in a "clean, list-like organisation of content", according to the Gemini FAQ[^].
While I agree that the list-like organization can be nice, I often had to end a paragraphs with "here is a link to X:", which breaks the flow of reading, and adds a lot of unnecessary newlines. So I wanted to find a way to add inner links which didn't veer too far from the spirit of gemini.
And today I found the solution! Taking the first paragraph of this post as example, the gemini looks like this:
When I first started working on <<this website>>, I thought we might host it on <<Gemini>>. Gemini is a minimal internet protocol as well as a text-based format for pages. => ../../home.gmi ARC Home Page => https://gemini.circumlunar.space/ Project Gemini
Which becomes:
When I first started working on this website, I thought we might host it on Gemini[^]. Gemini is a minimal internet protocol as well as a text-based format for pages.
In places where I had two short paragraphs, each one ending with "here is a link to X:", I can now combine them into one paragraph using inner links. This saves space and is more readable even in the plain text, so even the gemini benefits from this.
So I'm very pleased with this solution! The plain text looks clean (and therefore so does the gemini), the list-like organization is preserved, and the html gets to have a few inner links :)
We've added many other extensions to the gemini format in our html generator. One of these is a new "inline hint" link type, which looks like this:
==> resources/images/ARCLogo_small.png ARC Logo (small)
This is for links which can be inlined, which is especially useful for images. In HTML the image is loaded automatically, but on gemini I imagine the user would have to choose whether or not to do any inlining, in order to preserve gemini's one request per page policy. For gemini clients who don't support inlining, this would behave just like a normal link.
This extension is unfortunately incompatible with existing gemini clients, who will not interpret this as a link.
Another extension is wikilinks. Surround some text with double square brackets, and the text will become a link to the corresponding webpage. Wikilinks look like this:
This is a wikilink: [[my link]].
The "my link" text becomes a link to "my-link.html" (or "my-link.gmi" on a gemini page).
This does somewhat break the "list-like organisation" of links, but I think it's fine, since the link stays on the same website, is easy to understand, and looks fine even on gemini viewers that don't support them.
Our website has links to sections of a document using URI Fragments. For example here is a link to this section. I'm not sure if any gemini viewers support such links, but I think it's important to have a standard for this, because on very long pages being able to link to a specific section is very useful.
My proposal: a link like => #My_Header should jump to the first heading whose text is either exactly My Header or My_Header.
We've also added all sorts of directives, configured using lines that look like @@ key value. For example, @@ lang en is on every page, and adds the lang="en" attribute in the html. Another is the @@ favicon, to set the favicon. Or @@ toc, which is used to generate a table of contents. We use these for automation and metadata.
At this point we've added so much stuff that we'd need a gemini generator for our gemini pages!
I'm having a lot of fun with this :)
Update 2021-02-11: This post has been slightly updated to use the new inner block formatting which was implemented today.
Date: 2021-01-28
Latest Edit: 2021-02-11
Author: Galene