# minrss, a lightweight feed reader

2023-05-14

![](/public/img/minrss-mrss.jpg)

## 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](https://newsboat.org/).
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](http://tools.suckless.org/ii/) and [sic](http://tools.suckless.org/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