Gemtext
Gemtext is a file format that’s a lightweight alternative to HTML, and it makes me happy.
It’s part of the
Gemini protocol, which also provides an alternative to HTTP. The two together are a beatifully minimal technology that recalls what the Web used to be, while at the same time taking advantage of modern niceties such as Unicode and TLS (encryption).
Why am I writing about it here? Because much of good design is about choosing
not to do things, and for this web page I based most of those decisions on Gemtext.
Whitespace
Gemtext is easy to write by hand, and at first glance looks like Markdown.
## Whitespace
Gemtext is easy to write by hand, and at first glance looks like Markdown.
But, unlike Markdown, Gemtext renders whitespace exactly as written. So, to write a paragraph in Gemtext, you write
one line. You only write a line break when you want one: at the end of a paragraph.
This is so surprisingly simple and effective that it’s surprising that it’s surprising. What have we been doing all these years?
…when you want one: at the end of a paragraph.
…surprising. What have we been doing all these years?
Because the responsibility for a good editing experience with Gemtext has been pushed to the editor—you need one that can “soft wrap”—the file itself is almost 100% semantic information. This makes Gemtext very unusual among human-readable file formats in that it does not need a formatter.
Links
Gemtext does not support inline links.
The only way to get a link is to dedicate a whole line to it.
=> https://www.google.com Google
And then it’s rendered with its own line.
🔗 Google
This shifts emphasis from links to text: a link costs as much as a paragraph, so you only link to something if it’s that important, and then you spend at least a paragraph explaining why it’s important.
I like it. It’s “slower”, more deliberate; I suppose, a bit like the difference between a newspaper and a book. What do you think?
All the rest
You’ve already seen code blocks; there are also blockquotes. And for the rest, I refer you to the source of truth.
The format is designed to be both as simple to write by hand and as simple to parse as practical. The essential structure of a gemtext document is flat, not hierarchical, and a document can be parsed and rendered correctly in a single top-to-bottom pass.
🔗 Gemini hypertext format, aka “gemtext”, specification
How I broke it
So, when putting together this web page the first thing I did was write a Gemtext to HTML converter in Dart.
It’s not a faithful implementation:
- Gemtext has no inline images. You can link to an image, and then the client can choose to display it or not. A common choice is “display inline on click”. I decided to be quite restrained in how I use images, but to have them display automatically.
- Gemtext has no way to emphasize words. I find using emphasis to be an important part of writing, so I added a nonstandard way to do it.
So I’m
mostly using Gemtext, but I did make a few tweaks.
And rendered it
In terms of the concrete appearance in HTML I was inspired by Lagrange, a beautiful browser for Gemini.
🔗 Lagrange
One of the recurring ideas behind HTML is that you can write what you
mean and the browser decides how to render it. Only, that hasn’t really happened. The defaults don’t look good: so you want to pick something, so all web pages end up looking different.
Gemtext in contrast has no way to specify rendering, so it really is entirely up to the browser. Everything can look good, everything can look consistent.
The Web has passed that point, and will never again look consistent.
📄 Web
📄 Gemtext