Source files and build scripts for my personal website
git clone
Download | Log | Files | Refs | README (7434B)

      1 # The gemini protocol
      3 My website is also available as a *gemini capsule* at
      4 [gemini://](gemini://
      5 Can't open this link? Of course, you'll need a *gemini* browser for that!
      7 [Gemini]( is a very young (2019) internet
      8 protocol similar to the mcuh more famous
      9 [HTTP](, with
     10 the design goal of being much simpler.
     11 Gemini pages are written in *gemtext*, a very simple markup language that
     12 offers headers, hyperlinks, lists and little more - notably, there is no
     13 inline formatting.
     15 **Disclaimer**: I am not a networking expert, so I will keep this article
     16 at a very basic level. Nonetheless I may end up writing wrong or inaccurate
     17 things. If you know this stuff better than me and you spot a mistake, feel
     18 free to [send me an email](
     20 ## Protocols: gemini:// and http://
     21 In the context of computer networks, a *protocol* is a set of rules that
     22 describes how two different machines should communicate to exchange data.
     23 If you are viewing this page in a normal web browser, the address in your
     24 address bar probably starts with `http://` (or `https://`, but let's pretend
     25 they are the same thing). This means that your device is communicating with
     26 the server where I have uploaded this page using the *Hypertext Transfer
     27 Protocol*. Concretely, your browser has sent the server a message such as
     29 ```
     30 GET /blog/index.html HTTP/1.1
     31 Host:
     32 ```
     34 And the server has replied something like
     36 ```
     37 HTTP/1.1 200 OK
     38 Connection: keep-alive
     39 Content-Length: 1131
     40 Content-Type: text/html
     41 Date: Fri, 03 Jun 2022 14:34:22 GMT
     42 Last-Modified: Sun, 29 May 2022 11:15:55 GMT
     43 Server: OpenBSD httpd
     45 <!doctype html>
     46 <html lang="en">
     47 <head>
     48 	<title> Blog | Sebastiano Tronto </title>
     50 (...Some more stuff...)
     52 </html>
     53 ```
     55 So there is some garbage that you don't care about (your browser does),
     56 plus the actual content that you want to view. What exact garbage your 
     57 browser and the server should exchange before one ships the actual content
     58 to the other is exactly what the protocol defines. Calling it "garbage"
     59 is a bit unfair, because there can be some useful information: for example,
     60 when the page was last modified, so if your browser has already seen and
     61 cached this page it does not need to download it again, but there could
     62 be more stuff such as error messages or redirection paths.
     64 In contrast, a gemini browser might send a request that looks like
     66 ```
     67 gemini://
     68 ```
     70 To which a gemini server would respond simply
     72 ```
     73 20 text/gemini; 
     74 # Blog
     76 (...Some more stuff...)
     77 ```
     79 Very briefly, this is how the two protocols work. You might be wondering how
     80 exactly your browser is sending and receiving this information. Well, http
     81 (and gemini) sit on top of other protocols which describe exactly this. These
     82 other protocols in turn are on top of other protocols and... basically,
     83 [it's protocols all the way down](
     85 (*If you are curious where I got the server responses from: the UNIX command
     86 `curl` and the gemini browser [`gmni`](
     87 have a `-i` option that allows to see the messages received from the server.*)
     89 ## The gemtext markup language
     91 Web pages are usually written in the
     92 [HTML]( format. There are plenty of
     93 resources to learn how HTML works, so I will not explain it here.
     94 Very briefly,
     95 using tag pairs such as `<h1></h1>`, `<p></p>` or `<a href="..."></a>`,
     96 an html file tells your browser how to display its content. It may
     97 also embed images, videos or even executable scripts.
     99 Gemtext plays the same role for gemini pages, but it has (by design)
    100 a much more restricted feature set. It's syntax is somewhat similar to
    101 [Markdown](, another markup language.
    102 For example, headings and (unordered) lists work in the same way:
    104 ```
    105 # A title
    106 ## A second-level heading
    107 There are only 3 levels of heading in gemtext
    108 ### This is the last level
    109 Lists:
    110 * one
    111 * two
    112 * three
    113 ```
    115 There is however a fundamental difference in how lines are parsed: in gemtext,
    116 newlines in the code are preserved. This sounds completely normal for anyone
    117 used to modern word processors, but it is different from how HTML, Markdown
    118 and LaTeX work, just to name a few. In practice, this means that in gemtext
    119 you have to write your paragraphs as long lines, without inserting line breaks
    120 unless you want the line to be broken at that specific point.
    121 This may be annoying for people who use old-style line-based editors, such as
    122 vi, but it makes parsing a gemtext file much simpler.
    124 There are only three other things you can do in gemtext: links, block quotes
    125 and preformatted text.
    127 Links consist of a single line starting with `=>`, followed by a link and
    128 (optionally) by the text you want to appear instead of the URL of the link.
    130 ```
    131 => gemini:// A link to my homepage
    132 ```
    134 Blockquotes are simply lines starting with `>`:
    136 ```
    137 > This is a quote
    138 ```
    140 Finally, preformatted text is any text between two lines consisting of three
    141 backticks. It is going to appear as it is when rendered, i.e. your browser
    142 won't parse any gemtext syntax inside preformatted text.
    144 ````
    145 ```
    146 This is preformatted text
    147 It can be useful to display ASCII art, like this
    148  /\_/\
    149 ( o.o )
    150  > ^ <
    151 => This line will not be interpreted as a link
    152 ```
    153 ````
    155 (*If you are reading this via gemini, the lines above are not properly
    156 displayed.  I'll edit this page if I find a way to escape the triple backtick,
    157 or fix the markdown-to-gemtext conversion*)
    159 And that's it, you now know gemtext. There is no inline formatting, no
    160 embedded media, no CSS - your browser will take care of the styling and
    161 if you want to view a picture you can just download it and open it with
    162 an external app.
    164 ## Gemini in practice
    166 Gemini is basically a very stripped down version of the Internet. To me it
    167 feels like some kind of very niche, underground web. Some *capsules* I like
    168 browsing are [](gemini:// and
    169 [](gemini:// I don't have an account there
    170 yet, but I think I will make one at some point. I also check the
    171 [Antenna feed aggregator](gemini:// to discover new
    172 stuff.
    174 Basically, if you like the idea of a small and text-only version
    175 of the internet, you should check out the gemini space.
    176 The page []( suggests some
    177 browsers - I personally use gmnln, but it is more or less an interactive
    178 curl, you probably won't like it.
    180 ## Conclusions
    182 I think gemini is an interesting exercise of minimalism, which I like.
    183 I am not a networking expert, so I don't know what the pros and cons of using
    184 gemini:// rather than http(s):// are, but I quite like gemtext as a markup
    185 language. I am not too fond of using long lines, but this is not
    186 a deal-breaker. However, I still prefer making use of a few of the extra
    187 features that html offers, such as inline formatting.
    189 I will keep offering this website in gemtext via gemini://, but it will
    190 stay html-first. This means that inline links will look a bit ugly in gemini
    191 and, more annoyingly for the few gemini users, I am going to use
    192 http(s) links even when a gemini counterpart is available.
    194 *Update: as of August 2023, my website is still available on gemini,
    195 but new blog posts are no longer mirrore there*