(February 14, 2024 Update: I took down our Osmosfeed Aggregator after running into some technical issues and not having time to figure out how to resolve them. You will find this article as I originally published it but with links that no longer work removed.)

I came across an open source project called osmos::feed on GitHub (heretofore “Osmosfeed”). Osmosfeed describes itself as follows: “An RSS reader running entirely from your GitHub repo.” The feed reader’s output can be hosted for free with GitHub Pages, GitHub’s static website hosting. I thought the project was intriguing when I discovered it. I decided to use it to create a single feed site with all of The New Leaf Journal’s feeds and other feeds related to our external projects and presences. Below, I will introduce the project as a new member of the growing New Leaf Journal family.

If you are not familiar with RSS and ATOM feeds, I recommend reading my introduction to feeds and feed readers. I also offer arguments for feeds as alternatives to social media (see posts on Facebook and Twitter), curating your feeds, and using a feed reader in conjunction with a read-it-later solution. You can find all of our feeds here.

Notes on Updates

If I make any significant changes to our Osmosfeed site’s design, name, or hosting situation, I will post an update here. I will not update this article for minor changes (e.g., adding or removing feeds from our collection).

What is Osmosfeed?

The open source code for Osmosfeed is available in a GitHub repository maintained by osmos::craft (heretofore “Osmoscraft”).

I am not well-equipped to provide a technical explanation, and people who are can study the code for themselves. I will focus on what the tool actually does.

Osmosfeed is an RSS/ATOM feed reader which runs from a GitHub code repository. One can use GitHub’s free static website hosting, GitHub pages, to present the articles or other media pulled from feeds (you can also host the actual site elsewhere, e.g., Netlify). The design of the site can be customized with HTML and CSS templates.

There are many samples of what Osmosfeed sites can look like in its examples repository.

Creating an Osmosfeed Website

I have very little experience with managing GitHub repositories. Thus, it is a credit to the Osmosfeed docs that I was able to set up New Leaf Journal Feeds without too much difficulty. There is little reason for me to offer a guide since Osmoscraft does a fine job, so I will simply explain the general outline to provide some background for my project.

In order to create an Osmosfeed website, I created my own GitHub repository from the osmosfeed-template repository. Next, I activated GitHub pages for the repository.


Well not quite. I had a few technical issues stemming from my not having much GitHub knowledge. You can see the full commit history here. My site did not work initially, but after looking at the options, I figured out that I had a permissions issue with the GitHub token (see commit). While I was trying to fix the permission issue, I changed two dependencies to newer versions. While I am not sure if I was supposed to do that, it ended up working without issue and cured a couple of GitHub warning messages during building.

Customizing New Leaf Journal Feeds

From the outset, note that I did not change the default appearance of New Leaf Journal Feeds while making the site. For my purposes, the default template is acceptable enough that I am not inclined at this time to try to figure out how to change the appearance (web design is not my area).

The most important thing about an Osmosfeed site is the feeding it feeds (it is a feed reader, after all). Feeds are set in the osmosfeed.yaml file in the main repository (see our osmosfeed.yaml). I will add more feeds going forward, but as an initial matter, I added all of our New Leaf Journal feeds, Victor V. Gurbo’s YouTube channel feed, and some of my non-New Leaf Journal feeds (including my Pixelfed ATOM feed). I also used the osmosfeed.yaml to set the site name (New Leaf Journal Feeds) and its timezone (New York).

I then edited our update-feed.yaml file to change how often our site refreshes. By default, Osmosfeed updates once per day at midnight, UTC. I wanted it to update a few times per day instead of just once. I am not too familiar with UTC, but I learned that it runs four hours ahead of New York City’s Eastern Standard Time. With that knowledge, I set it to update at 9 AM, 1 PM, and 6 PM (after an initial failure).

By default, Osmosfeed keeps posts for 30 days. I consider this acceptable so I did not change the default behavior.

The Result

New Leaf Journal Feeds is a one-stop shop for finding all new New Leaf Journal posts (Articles, Leaflets, Leaf Buds, and newsletters) in one place along with some external posts from me and Victor V. Gurbo.

(However, for reasons I explain in our Feeds guide, I generally recommend subscribing directly to The New Leaf Journal’s feeds if you are using a feed reader – but the choice is yours.)

I plan to work on New Leaf Feeds periodically going forward, adding some new feeds and possibly, at some point in the future, working on the design. I think the default look is solid, but I do not like the way it handles New Leaf Journal excerpts (it starts with part of the first sentence of the article and then skips to our related posts). But as a place for aggregating our writing and media from many sources, it works well.

Who is it For?

New Leaf Journal Feeds feeds is for all New Leaf Journal fans (plural, I hope) and people who are interested in seeing some non-New Leaf Journal posts from me and Victor V. Gurbo. As I noted, we may expand the project in the future.

People who use feed readers and who subscribe to The New Leaf Journal may not have a major use-case for New Leaf Journal Feeds. As I noted, I recommend subscribing directly to feeds of interest in a feed reader. Its main use for people who already use feed readers may be that it will often include posts that are no longer in our main feed (for example, The New Leaf Journal’s feeds serve our 12 most-recent articles within the given feed).

But for the majority of you who do not use feed readers, New Leaf Journal Feeds gives you a free to use feed-aggregator experience for all of our projects. All you need to do is navigate to the URL and bookmark it in your favorite web browser to stay on top of all of our updates.

Why GitHub Pages For Hosting?

GitHub is owned by Microsoft. The Bing Search Engine is owned and run by Microsoft. Bing de-indexed The New Leaf Journal. Moreover, I switched from using Windows to using Linux back in August 2020. Taken together, I am not a big fan of Microsoft at the present moment (they will get a few points back of they re-index and un-blacklist The New Leaf Journal). By creating a Osmosfeed site and hosting it on GitHub, I ensure that Microsoft will have our links… somewhere.

I kid (maybe).

But jokes aside, Osmosfeed provides very clear instructions for easily setting up a site with GitHub pages. Were I using Osmosfeed more seriously – for example as the backbone of a larger project – I would probably host the actual site off GitHub (perhaps with Netlify, which is an option noted in the docs). Using an option such as Netlify or another static web host would also be good for people who are already using GitHub Pages for a site on GitHub’s free tier.

But for now, this is just a small experiment and a fun new way for people to stay on top of the newest writing and media from me and the distinguished Mr. Gurbo. It is for that reason that I am fine with hosting New Leaf Journal Feeds on GitHub for the time being.