Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/exaroth/i3-news

Interactive RSS/Atom news headlines plugin for i3wm and sway - compatible with i3status, i3blocks, polybar and waybar
https://github.com/exaroth/i3-news

i3 i3blocks i3status news polybar rss sway waybar zig

Last synced: 4 months ago
JSON representation

Interactive RSS/Atom news headlines plugin for i3wm and sway - compatible with i3status, i3blocks, polybar and waybar

Awesome Lists containing this project

README 

          
# I3 News [![Licence](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Zig-0.14.1](https://img.shields.io/badge/zig-0.14.1%2B-orange.svg)](Zig-0.14.1)


















__I3 News__ let's you create interactive news headline snippets compatible with various i3/sway bar plugins, based on user defined RSS/Atom feeds. 



Compatibility list:



- i3blocks

- polybar

- i3status

- waybar

 

#### Table of Contents



- [Installation](#installation)

    - [Building from source](#building-from-source)

- [Usage](#usage)

    - [i3blocks](#i3blocks)

    - [i3status](#i3status)

    - [Polybar](#polybar)

    - [Waybar](#waybar)

- [Dynamic headlines](#headline-tick-scroll-and-paginate-commands)

    - [i3blocks](#i3blocks-integration)

    - [Polybar](#polybar-integration)

	- [Waybar](#waybar-integration)

	- [Dynamic headline options](#dynamic-headline-options)

- [Configuration](#configuration)



### Installation

> [!NOTE]

> i3 news requires `fuse`/`libfuse` libraries installed in the system



I3 news ships with 2 versions available:



- __Light__ - Includes only i3 news binary and supplementary scripts, it does not contain [Newsboat](https://newsboat.org/) RSS reader required for retrieval of RSS data, you will need to install Newsboat package system wide (Note: Snapcraft version is not supported) (__Recommended__)

 

 

To install this version execute:

``` bash

sh -c "$(curl -fsSL https://raw.githubusercontent.com/exaroth/i3-news/master/install.sh)"

```

- __Self Contained__  - this is the same as above but ships with Newsboat app and all required shared libraries included. To install run:

 

``` bash

sh -c "$(curl -fsSL https://raw.githubusercontent.com/exaroth/i3-news/master/install_full.sh)"

```



You can also download `i3-news` executables from [releases](https://github.com/exaroth/i3-news/releases) page.



Following the installation update your crontab to set up regular RSS feed reloads , eg to update feeds every 20 minutes:



`crontab -e`



``` crontab

*/20 * * * * /usr/local/bin/i3-news reload

```

 

#### Building from source



__Note__: Supported zig versions - `0.14.1`/`0.15.0`



Clone the repository and run `make build-appimage` to compile the source and build AppImage for the executable.



### Usage



```

Usage: i3-news ? 



Commands: open|reload|tick|scroll|paginate|version



Options:

  -c, --configs       Snippet configuration or configurations to use

  -s, --i3status      I3status output

  -b, --i3blocks      I3blocks output

  -p, --polybar       Polybar output

  -w, --waybar        Waybar output

  -a, --add-config    Add new i3-news configuration

  -r, --rm-config     Remove existing configuration

  -e, --edit-config   Edit urls for given configuration

      --get-url       Retrieve url for currently displayed headline

      --plain         Plain output

      --random        Retrieve headlines using random strategy

      --latest        Retrieve headlines prioritising latest articles

      --debug         Print debug info

  -h, --help          Print help

```



### Creating new snippet



In order to create new I3 news snippet execute:



``` sh

i3-news -a 

```



You will be prompted to enter list of RSS/Atom urls which will be tracked by the snippet.



Use 

```

i3-news -e 

```

To edit snippet urls, or

```

i3-news -r 

```

to remove existing one.



Snippet configurations are stored at `$HOME/.config/i3_news/`.



### Integration with i3 bar plugins.



#### Static headllines



#### i3blocks

In order to add i3 news snippet to i3blocks bar edit existing configuration (typically stored at `~/.i3blocks`) adding following entry:



```

[News]

command=/usr/local/bin/i3-news -b -c 

interval=30

```

(`interval` value will determine how often headlines will be refreshed)



Additionally in order to customize browser command to use when opening headline url you can use `I3_NEWS_BROWSER_CMD` env variable, for example to open url in new firefox tab use:



```

command=I3_NEWS_BROWSER_CMD="/usr/bin/firefox --new-tab" /usr/local/bin/i3-news -b -c 

```



#### i3status



> [!NOTE]

> i3status plugin is non-interactive, thus clicking on headline wont result in opening of the url in the browser

 

Edit `i3` configuration (typically stored at `~/.config/i3/config`) and locate `bar { ... }` block containing

```

status_command  i3status

```



entry, replace it with:



```

status_command  i3status | /usr/local/bin/i3-news -s -c 

```



You can also output more than 1 snippet by passing comma delimited list of snippet names as part of `-c` parameter.



#### polybar



Edit polybar configuration file (usually stored at `~/.config/polybar/config.ini`), add following entry:



``` ini

    [module/i3-news]

    type = custom/script

    exec = /usr/local/bin/i3-news -p -c 

    tail = true

    interval = 10

    click-left = /usr/local/bin/i3-news open -c 

```

then update either `modules-left` or `modules-right` entry with `i3-news`.



Similarly to `i3blocks` integration you can customize browser used for opening headline urls by adding `I3_NEWS_BROWSER_CMD` env when executing `click-left` handler.



#### waybar



Edit waybar configuraton (typically stored at `~/.config/waybar/config`), add following entry



``` json

    "custom/i3-news": {

        "exec": "/usr/local/bin/i3-news -w -c ",

        "return-type": "json",

        "interval": 10,

        "tooltip": false,

        "on-click": "/usr/local/bin/i3-news open -c "

    }

```



and update `modules-right`, `modules-left` or `modules-center` with `custom/i3-news` entry.



You can customize color rendering by editing `~/.config/waybar/style.css` and adding



``` css

#custom-i3-news. {

    color: white;

}

```



### Headline tick, scroll and paginate commands



__I3 News__ ships supplied with commands for outputting dynamic text headlines, these are useful particularly if your bar setup requires constant widget width. Dynamic headlines are not available for `i3status` integration.



Available commands:



#### ticker






`tick` command will output infinite feed of scrolling headlines, new headlines will be retrieved and inserted automatically.



#### scroll






`scroll` command will scroll single headline if it exceeds widget width, otherwise it will output static text.



#### paginate






`paginate` command will split text into multiple pages if it exceeds widget width, otherwise headline text will be displayed as is.



#### Usage



Usage for dynamic headline commands is as simple as calling:



```

i3-news  -c 

```

where `` is `tick`/`scroll`/`paginate`, you can also pass arguments which modify headline retrieval strategy such as `--latest` or `--random`



##### I3blocks integration



Example usage in i3blocks config (`markup=pango` and `interval=persist` settings are required), also pass `I3_NEWS_OUTPUT_PANGO` env variable to ensure that output text is rendered with monospace font.



```

    [NEWS]

    command=I3_NEWS_OUTPUT_PANGO=1 /usr/local/bin/i3-news  -c 

    markup=pango

    color=#FEC925

    interval=persist

```



##### Polybar integration



Reference configuration, note there's no need to include `interval` field for scrolling snippets.

```

    [module/i3-news-scroll]

    type = custom/script

    exec = /usr/local/bin/i3-news  -c 

    click-left = /usr/local/bin/i3-news open -c 

    tail = true

```

> [!NOTE]

> If you pass any additional arguments to the dynamic headline command such as `--latest` or `--random`

> make sure to pass same set of commands to `open` as well, this also applies to Waybar integration.



##### Waybar integration



``` json

    "custom/i3-news-scroll": {

        "escape": "true",

        "exec": "/usr/local/bin/i3-news  -c ",

        "max-length": 50,

        "min-length": 50,

        "on-click": "/usr/local/bin/i3-news open -c "

    }

```



#### Dynamic headline options



Dynamic headlines can be configured by passing various env vars to `i3-news` executable , most straightforward way to do it is to pass them as a prefix when calling the executable, eg.



``` bash

ENV_VAR=val `i3-news` 

```

Available settings:



- `I3_NEWS_INTERVAL` - (`scroll`/`paginate` only) Defines how often to swap headlines (in seconds)

- `I3_NEWS_DELAY` - Refresh interval when outputting text, will determine scrolling speed for `tick` and `scroll` commands and speed of changing pages for `paginate` command

- `I3_NEWS_WIDTH` - Width of the snippet

- `I3_NEWS_ALIGN` - (`paginate` command only) Set text alignment when outputting text, available values: `left`, `right`, `center`

- `I3_NEWS_OUTPUT_PANGO` - Output text in `pango` format (with monospace font set).



### Configuration



Configuration for each snippet is stored at `~/.config/i3_news//config` with following options available:



- `max-article-age` - amount of hours in the past for which to display headlines for

- `output-color` - text color for given snippet (hex based)

- `refresh-interval` - (i3status only) refresh rate when displaying the headlines



### License

See `LICENSE` file for details