wb5/posts/minrss.md

minrss, a lightweight feed reader

2023-05-14

purpose

If you want to read content online from many different websites, the best way is to subscribe to RSS or Atom feeds. It's a simple, universal format for getting content onto your screen.

I personally enjoy living in the terminal. One of the more popular RSS readers for this environment is Newsboat. Newsboat has tons of useful features and a pretty TUI, and I did use it for a while.

However, I thought that it was too complex for what I needed in an RSS reader. Therefore, I decided to write a new one: MinRSS.

concept

MinRSS is a small binary that "does one thing and does it well": it downloads RSS articles to disk.

Essentially, every feed is represented as a folder, and individual articles are files in these folders.

Every time the binary is run, it creates a structure like this in the current working directory:

rss
|--news
|  |--article1
|  `--article2
`--blog
  |--post
  `--other_post

If an article is new (it wasn't on disk already), its filename is printed to standard output.

The goal of doing things this way is to make writing scripts as easy as possible. If you're familiar with shell scripting, all you need is jq and you can now parse RSS and implement any custom feature you want.

If you felt masochistic, you could even read RSS feeds using only your shell, minrss, ls, head and w3m.

This sort of structure is inspired by suckless.org's ii and sic.

wrapper script

I wrote my own wrapper script around MinRSS, called mrss. It has the following features:

• Update feeds using MinRSS
• Show all new articles using fzf as an interface (as seen in the screenshot above)
• Mark articles as read
• Mark articles as "watch later"
• Custom handler for opening videos and podcasts in mpv

installation

First, ensure you have the requirements:

• libcurl
• libxml2
• json-c
• xdg-open

Clone the repo:

git clone https://github.com/dogeystamp/minrss
cd minrss

Edit the config file. The comments in config.h should guide you:

cp config.def.h config.h
vim config.h

MinRSS outputs human-readable output by default. The wrapper script will only work with these options set:

static const enum outputFormats outputFormat = OUTPUT_JSON;
static const enum summaryFormats summaryFormat = SUMMARY_FILES;

Then, build and install MinRSS:

make install

Install the wrapper script:

cp contrib/mrss.sh ~/.local/bin/mrss
chmod 755 ~/.local/bin/mrss

usage

For complete help, run mrss -h.

To get started, all you need is mrss update to update feeds, then mrss fzf to view articles. Articles are, by default, saved to ~/rss, but you can set $MRSS_DIR to change this.

fzf shortcuts

In mrss fzf's interface, the following commands are available:

Command	Shortcut	Description
/read	Enter	Opens link in the browser or mpv
/purge	Ctrl-D	Mark article as read
/purge-all	Ctrl-Alt-D	Mark all articles as read
/watch-later	Ctrl-W	Send article to the watch-later folder
/queue	Ctrl-E	Queues link to be opened after leaving fzf

You can also use Tab and Shift-Tab to select multiple articles to be acted upon.

viewing specific folders

The mrss fzf command can be used to view a specific folder's contents.

To read all null-program articles (regardless of if they are marked read or not):

mrss fzf null-program

To view new null-program articles:

mrss fzf new/null-program

To see articles you've marked as "watch later":

mrss fzf watch-later

creating meta-feeds

In the latest version of mrss, you can create tags to categorize your feeds. First, create a directory for your tag under $MRSS_DIR:

mkdir ~/rss/tag

To include new articles for a given feed:

ln -sr ~/rss/new/feed ~/rss/tag/

To include all articles:

ln -sr ~/rss/feed ~/rss/tag/

To view this tag:

mrss fzf tag