💾 Archived View for geminiprotocol.net › docs › companion › subscription.gmi captured on 2024-08-31 at 11:43:17. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2023-09-08)
-=-=-=-=-=-=-
This document describes a convention whereby Gemini clients can "subscribe" to a regularly updated Gemini page (such as the index page of a gemlog) even in the absence of a full-fledged syndication technology like Atom or RSS. It is intended as a lightweight alternative to such technologies to lower the barriers to publishing serial content in Geminispace which can be easily followed without tedious regular manual checking of bookmarks. In particular, it is an explicit goal that a simple, manually-updated, human readable index page of the type content authors would likely create anyway should be able to subscribed to without any special changes being necessary. Obviously, such a convention will be less powerful than more complicated technologies such as Atom and will not work as well as more complicated technologies in all conceivable use cases. Nevertheless, it is expected to function adequately for a wide range of reasonable use cases. Nothing in this convention prevents content authors from simultaneously publishing an Atom feed if they wish to. In fact, this convention can ease the generation of said feeds.
The remainder of this document describes how to interpret a single text/gemini document as if it were an Atom feed with all required elements present. The convention is described this way to ensure it is possible for clients to support both this lightweight subscription convention and subscribing to Atom feeds with a simplified codebase and consistent UI, and to demonstrate how simple automatic generation of Atom feeds is possible. Simpler clients which support only this subscription convention are free to ignore Atom elements as they see fit.
The URL from which the text/gemini document is fetched serves as the feed's required "id" element and the recommended "link" element.
The contents of the first header line in the document beginning with a single # serves as the feed's required "title" element. For this reason, authors are encouraged to use titles which provide their own context, e.g. "Abelard Lindsay's gemlog" rather than "My gemlog" or "Gemlog index".
If a header line beginning with ## occurs in the document after the first line beginning with a single # but before any non-empty, non-header lines, its contents may serve as the feed's optional "subtitle" element.
A feed's required "updated" element should be set equal to the most recent value from all the associated entry's required "updated" elements. If no entries can be extracted from the document, then the feed is empty (which is permitted by the Atom standard), and the feed's "updated" element should be set equal to the time the document was fetched.
A feed's entry elements are derived from a subset of its link lines, if any are present.
Each link line where the URL is followed by a label whose first 10 characters correspond to a date in ISO 8601 format (i.e. YYYY-MM-DD) represents a single entry. Link lines which do not meet this criteria are ignored.
An entry's required "id" element and required "link" element with rel="alternate" ("link" elements are optional in Atom entries in general, but this convention does not assign "content" elements to entries and therefore a rel="alternate" link becomes required) are both equal to the URL of the corresponding link line.
An entry's required "updated" element is noon UTC on the day indicated by the 10 character date stamp at the beginning of the corresponding link line's label.
An entry's required "title" element is derived from what remains of the corresponding link line's label after discarding the first whitespace-separated component (which necessarily includes the date stamp). Clients may simply take the entirety of the remainder, but some simple sanitisation may be attempted to account for the fact that users may e.g. use labels with a separator between date and title such as "1965-03-23 - Gemini 3 launch successful!".
The Gemini document below, served from gemini://gemini.jrandom.net/gemlog/:
# J. Random Geminaut's gemlog Welcome to my Gemlog, where you can read every Friday about my adventures in urban gardening and abstract algebra! ## My posts => bokashi.gmi 2020-11-20 - Early Bokashi composting experiments => finite-simple-groups.gmi 2020-11-13 - Trying to get to grips with finite simple groups... => balcony.gmi 2020-11-06 - I started a balcony garden! ## Other gemlogs I enjoy => gemini://example.com/foo/ Abelard Lindsay's gemlog => gemini://example.net/bar/ Vladimir Harkonnen's gemlog => gemini://example.org/baz/ Case Pollard's gemlog => ../ Back to my homepage Thanks for stopping by!
may be interpreted as equivalent to the following Atom feed:
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
<title>J. Random Geminaut's gemlog</title>
<link href="gemini://gemini.jrandom.net/gemlog/"/>
<updated>2020-11-20T12:00:00Z</updated>
<id>gemini://gemini.jrandom.net/gemlog/</id>
<entry>
<title>Early Bokashi composting experiments</title>
<link rel="alternate" href="gemini://gemini.jrandom.net/gemlog/bokashmi.gmi"/>
<id>gemini://gemini.jrandom.net/gemlog/bokashmi.gmi</id>
<updated>2020-11-20T12:00:00Z</updated>
</entry>
<entry>
<title>Trying to get to grips with finite simple groups...</title>
<link rel="alternate" href="gemini://gemini.jrandom.net/gemlog/finite-simple-groups.gmi"/>
<id>gemini://gemini.jrandom.net/gemlog/finite-simple-groups.gmi</id>
<updated>2020-11-13T12:00:00Z</updated>
</entry>
<entry>
<title>I started a balcony garden!</title>
<link rel="alternate" href="gemini://gemini.jrandom.net/gemlog/balcony.gmi"/>
<id>gemini://gemini.jrandom.net/gemlog/balcony.gmi</id>
<updated>2020-11-06T12:00:00Z</updated>
</entry>
</feed>
The primary shortcoming of this convention is that it does not convey a time of day at which posts are made nor a timezone in which the date stamp is valid. This makes lightweight subscription a poor match for applications where multiple updates are expected each day and the relative order of updates (both within and across feed sources) is important, such as following breaking news headlines, weather updates, traffic conditions, etc. Such applications are strongly encouraged to instead implement more robust subscription technologies such as Atom or RSS.
This shortcoming is not expected to have serious implications for a wide range of common and valuable activities in Geminispace which operate at "human scale". For example, this convention is perfectly viable for an individual reader using their local client to subscribe to ten or twenty hand-picked gemlogs which update every few days with non-time-critical content about people's daily lives, hobbies, opinions on the state of the world, recipes, photos, etc. It is very rarely important to read content like this which was written by Alice on Wednesday morning before that which was written by Bob on Wednesday evening, or to know exactly when each person wrote their posts. If the time of day is relevant to the post content, the author will surely mention it.