I3 News

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
  • Building from source
• Usage
  • i3blocks
  • i3status
  • Polybar
  • Waybar
• Dynamic headlines
  • i3blocks
  • Polybar
  • Waybar
  • Dynamic headline options
• 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 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:

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:

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

You can also download i3-news executables from releases page.

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

crontab -e

*/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 ?<command> <options>

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:

i3-news -a <snippet_name>

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

Use

i3-news -e <snippet_name>

To edit snippet urls, or

i3-news -r <snippet_name>

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 <snippet_name>
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 <snippet_name>

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 <snippet_name>

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:

    [module/i3-news]
    type = custom/script
    exec = /usr/local/bin/i3-news -p -c <snippet_name>
    tail = true
    interval = 10
    click-left = /usr/local/bin/i3-news open -c <snippet_name>

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

    "custom/i3-news": {
        "exec": "/usr/local/bin/i3-news -w -c <snippet_name>",
        "return-type": "json",
        "interval": 10,
        "tooltip": false,
        "on-click": "/usr/local/bin/i3-news open -c <snippet_name>"
    }

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

#custom-i3-news.<snippet_name> {
    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 <command> -c <snippet_name>

where <command> 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, in order to properly render output text.

    [NEWS]
    command=I3_NEWS_OUTPUT_PANGO=1 /usr/local/bin/i3-news <tick/scroll/paginate> -c <snippet_name>
    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 <tick/scroll/paginate> -c <snippet_name>
    click-left = /usr/local/bin/i3-news open -c <snippet_name>
    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

    "custom/i3-news-scroll": {
        "escape": "true",
        "exec": "/usr/local/bin/i3-news <tick/scroll/paginate> -c <snippet_name>",
        "max-length": 50,
        "min-length": 50,
        "on-click": "/usr/local/bin/i3-news open -c <snippet_name>"
    }

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.

ENV_VAR=val `i3-news` <args>

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/<snippet_name>/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