Amfora's subscriptions feature allows you to "subscribe" to different feeds and pages, and see when they update on the about:subscriptions page. For example, many gemlogs have an Atom feed. With this feature, you can subscribe to that feed, and be aware of the latest posts.
If you've ever used CAPCOM or Spacewalk, this is very similar, but works right inside Amfora!
Types of Subscription
There are two types of things to subscribe to: feeds, and pages.
Feeds
Feeds are documents for computers to consume, that provide a list of "entries": posts, updates, whatever. When you subscribe to a feed, Amfora will download, save, and parse it, and then display the entries on the Subscriptions page. It will periodically check for updates and add them, while Amfora is open.
Amfora can work with Atom, RSS, and JSON Feed files. If you're an author and you want to set up a feed, I'd recommend an Atom feed as it's simple, modern, and widely accepted. You can use gemfeed to create one.
Pages
Page subscription allows you to watch a gemtext or plain text page for updates. When you subscribe to the page, Amfora creates and saves an ID (a SHA-256 hash) for its content, and it will periodically check (when Amfora is open) for updates, checking if the ID has changed. When the page changes, it will show up as an entry on the Subscriptions page.
It might not always be obvious what's changed. It could be anything from a single character that was added, to the entire page changing.
Which is better?
In general, you should prefer subscribing to feeds where possible. For example, if a gemlog has a hompage and a feed, it's usually better to subscribe to the feed instead of the homepage itself.
This is because a feed file will contain lots of other useful data that Amfora can display, like the name of the feed, the name of the post, the name of the author, when it was posted, etc. With a page, all you get is a URL and an inaccurate update time.
Page subscription is generally just used for specific pages that aren't part of a feed, or if a gemlog doesn't have a feed.
How to use it
To subscribe to a feed, go to the URL of a valid feed. A popup should appear asking if you want to subscribe. To subscribe to a page, go to the page, and then press Ctrl-X. A popup asking whether you want to subscribe will appear. You can also revisit any feed or page that you're already subscribed to, and when the popup appears you can choose to manually update that subscription.
You can view your subscription feed by going to about:subscriptions, or pressing Ctrl-A. It's also linked on the new tab page.
Managing Subscriptions
At the top of the Subscriptions page there is a link to about:manage-subscriptions. This page has a list of URLs, and when navigating to a URL, you will be unsubscribed. This cannot be undone, but if you have the still have the URL you can go back to it and subscribe.
Updating
Amfora will update your subscriptions on its own. It start updating every time it starts, making three requests at once in the background by default. It will also update 30 minutes after the last one completed, by default. This is all configurable, see the next section.
Configuration
Make sure that you've read the configuration wiki page first.
[subscriptions]
# For tracking feeds and pages
# Whether a pop-up appears when viewing a potential feed
popup = true
# How often to check for updates to subscriptions in the background, in seconds.
# Set it to 0 to disable this feature. You can still update individual feeds
# manually, or restart the browser.
#
# Note Amfora will check for updates on browser start no matter what this setting is.
update_interval = 1800 # 30 mins
# How many subscriptions can be checked at the same time when updating.
# If you have many subscriptions you may want to increase this for faster
# update times. Any value below 1 will be corrected to 1.
workers = 3
# The number of subscription updates displayed per page.
entries_per_page = 20
A note on "Gemini Feeds"
As I wrote in this comment:
The "gemini feed format" (gemini://gemini.circumlunar.space/docs/companion/subscription.gmi) will not be supported initially. It will likely be in a later release.
I plan on supporting it, but the UX of that is not super clean. To an unaware user, the difference between subscribing to the page vs subscribing to the page as a feed is not obvious. It might have to come in a future release, as I think the current features cover most use cases for now.
- makeworld, on Mastodon
Right now when visiting a page or feed, you can press Ctrl-X and it will ask you if you want to track it. One solution would be to check if the page is a valid gemini feed when Ctrl-X is pressed. But then you need to ask the user whether they want to track it as a page, or a gemini feed, and that's sorta hard to explain.
- makeworld, on IRC
Technical Details
If the original subscription URL redirects, that will be handled. Permanent redirects will change the URL, while temporary redirects will just be followed but not change the original URL. No matter the type of redirect, only up to 5 will be followed before stopping. See #144 for details.
All the data for this feature is stored in subscriptions.json. On Unix-based systems this is usually in ~/.local/share/amfora/, and on Windows it's in %APPDATA%\amfora\.
If you'd like to support Amfora development, you can sponsor me through Ko-Fi or Github Sponsors. Feel free to submit a PR as well! Thanks.