Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
https://github.com/aome510/hackernews-TUI

A Terminal UI to browse Hacker News
https://github.com/aome510/hackernews-TUI
article customizable hacker-news newsreader rust terminal tui vim
Last synced: 3 months ago
JSON representation
A Terminal UI to browse Hacker News
Host: GitHub
URL: https://github.com/aome510/hackernews-TUI
Owner: aome510
License: mit
Created: 2021-02-15T06:36:41.000Z (over 3 years ago)
Default Branch: main
Last Pushed: 2023-12-24T00:46:47.000Z (6 months ago)
Last Synced: 2024-01-07T06:28:19.050Z (6 months ago)
Topics: article, customizable, hacker-news, newsreader, rust, terminal, tui, vim
Language: Rust
Homepage:
Size: 41.6 MB
Stars: 448
Watchers: 6
Forks: 20
Open Issues: 2
Metadata Files:
- Readme: README.md
- License: LICENSE
Lists

awesome-hackernews - hackernews-TUI - A Terminal UI to browse HN. `MIT` (Clients / CLI & TUI)
awesome-tuis - hackernews-TUI
awesome-stars - aome510/hackernews-TUI - A Terminal UI to browse Hacker News (Rust)
cli-apps - hackernews-TUI - A Terminal UI to browse Hacker News. (<a name="viewers"></a>Viewers)
awesome-cli-apps - hackernews-TUI - A Terminal UI to browse Hacker News. (<a name="viewers"></a>Viewers)
README

        # hackernews-TUI

`hackernews_tui` is a fast and [customizable](https://github.com/aome510/hackernews-TUI/blob/main/docs/config.md) application for browsing Hacker News on the terminal.

`hackernews_tui` is written in Rust with the help of [Cursive TUI library](https://github.com/gyscos/cursive/). It uses [HN Algolia APIs](https://hn.algolia.com/api/) and [HN Official APIs](https://github.com/HackerNews/API) to get Hacker News data.

## Table of Contents

- [Install](#install)

  - [Binaries](#binaries)

  - [Using Cargo](#using-cargo)

  - [Docker Image](#docker-image)

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

  - [macOS](#macos)

  - [Arch Linux](#arch-linux)

  - [NetBSD](#netbsd)

- [Examples](#examples)

  - [Demo](#demo)

- [Default Shortcuts](#default-shortcuts)

  - [Global key shortcuts](#global-key-shortcuts)

  - [Edit key shortcuts](#edit-key-shortcuts)

  - [Key shortcuts for each View](#key-shortcuts-for-each-view)

    - [Story View](#story-view-shortcuts)

    - [Article View](#article-view-shortcuts)

    - [Comment View](#comment-view-shortcuts)

    - [Search View](#search-view-shortcuts)

- [Configuration](#configuration)

- [Authentication](#authentication)

- [Logging](#logging)

- [Roadmap](#roadmap)

## Install

### Binaries

Application's prebuilt binaries can be found in the [Releases Page](https://github.com/aome510/hackernews-TUI/releases).

### Using cargo

Install the latest version from [crates.io](https://crates.io/crates/hackernews_tui) by running `cargo install hackernews_tui --locked`.

### Docker image

You can download the binary image of the latest build from the `master` branch by running

```shell

docker pull aome510/hackernews_tui:latest

```

then run

```shell

docker run -it aome510/hackernews_tui:latest

```

to run the application. You can also use your local configuration file when running the image by running

```shell

docker run --rm -v ${CONFIG_FILE_PATH}:/app/hn-tui.toml -it aome510/hackernews_tui:latest

```

with `${CONFIG_FILE_PATH}` is the path to the local configuration file.

#### Building from source

Run

```shell

git clone https://github.com/aome510/hackernews-TUI.git

cd hackernews-TUI

cargo build --release

```

to build the application, then run

```shell

./target/release/hackernews_tui

```

to run the application, or

```shell

ln -sf $PWD/target/release/hackernews_tui /usr/local/bin

```

to link the executable binary to `/usr/local/bin` folder.

### Windows

#### Via Scoop

Run `scoop install hackernews-tui` to install the application.

### macOS

#### Via MacPorts

Run `sudo port install hackernews-tui` to install the application.

### Arch Linux

Run `yay -S hackernews_tui` to install the application as an AUR package.

### NetBSD

#### Using the package manager

```shell

pkgin install hackernews-tui

```

#### Building from source

```shell

cd /usr/pkgsrc/www/hackernews-tui

make install

```

## Examples

### Demo

Demo videos of `hackernews_tui` `v0.9.0` are available on [youtube](https://www.youtube.com/watch?v=m5O5QIlRFpc) and [asciinema](https://asciinema.org/a/459196)

[![asciicast](https://asciinema.org/a/459196.svg)](https://asciinema.org/a/459196)

### Story View

![Example of a Story View](https://user-images.githubusercontent.com/40011582/147393397-71991e48-cba6-4f89-9d28-cafbc0143c42.png)

### Article View

![Example of an Article View](https://user-images.githubusercontent.com/40011582/147393483-06b57c07-3fa3-49ec-b238-a2d67905610d.png)

### Search View

![Example of a Search View](https://user-images.githubusercontent.com/40011582/147393493-41d52d9f-65cd-4f63-bf76-c11d9bea1f49.png)

### Comment View

![Example of a Comment View](https://user-images.githubusercontent.com/40011582/147393459-641dd6c3-3564-472c-83cd-e1865339c861.png)

## Default Shortcuts

In each `View`, press `?` to see a list of supported keyboard shortcuts and their functionalities.

![Example of a Help View](https://user-images.githubusercontent.com/40011582/147393555-5ca346ca-b59a-4a7f-ab53-b1ec7025eca4.png)

The below sections will list the application's default shortcuts, which can be customized by changing the [key mappings](https://github.com/aome510/hackernews-TUI/blob/main/docs/config.md#keymap) in the user's config file.

For more information about configuring the application's key mappings or defining custom shortcuts, please refer to the [config documentation](https://github.com/aome510/hackernews-TUI/blob/main/doc/config.md#keymap).

### Global shortcuts

| Command                 | Description             | Default Shortcut   |

| ----------------------- | ----------------------- | ------------------ |

| `open_help_dialog`      | Open the help dialog    | `?`                |

| `close_dialog`          | Close a dialog          | `esc`              |

| `quit`                  | Quit the application    | `[q, C-c]`         |

| `goto_previous_view`    | Go to the previous view | `[backspace, C-p]` |

| `goto_search_view`      | Go to search view       | `[/, C-s]`         |

| `goto_front_page_view`  | Go to front page view   | `F1`               |

| `goto_all_stories_view` | Go to all stories view  | `F2`               |

| `goto_ask_hn_view`      | Go to ask HN view       | `F3`               |

| `goto_show_hn_view`     | Go to show HN view      | `F4`               |

| `goto_jobs_view`        | Go to jobs view         | `F5`               |

### Edit shortcuts

| Command                | Description                      | Default Shortcut |

| ---------------------- | -------------------------------- | ---------------- |

| `move_cursor_left`     | Move cursor to left              | `[left, C-b]`    |

| `move_cursor_right`    | Move cursor to right             | `[right, C-f]`   |

| `move_cursor_to_begin` | Move cursor to the begin of line | `[home, C-a]`    |

| `move_cursor_to_end`   | Move cursor to the end of line   | `[end, C-e]`     |

| `backward_delete_char` | Delete backward a character      | `backspace`      |

## Scrolling shortcuts

| Command     | Description             | Default Shortcut |

| ----------- | ----------------------- | ---------------- |

| `up`        | Scroll up               | `[k, up]`        |

| `down`      | Scroll down             | `[j, down]`      |

| `page_down` | Scroll up half a page   | `[d, page_down]` |

| `page_up`   | Scroll down half a page | `[u, page_up]`   |

| `top`       | Scroll to top           | `[g, home]`      |

| `bottom`    | Scroll to bottom        | `[G, end]`       |

### Shortcuts for each `View`

#### Story View shortcuts

| Command                        | Description                                           | Default Shortcut |

| ------------------------------ | ----------------------------------------------------- | ---------------- |

| `next_story`                   | Focus the next story                                  | `j`              |

| `prev_story`                   | Focus the previous story                              | `k`              |

| `next_story_tag`               | Go to the next story tag                              | `l`              |

| `previous_story_tag`           | Go to the previous story tag                          | `h`              |

| `goto_story`                   | Focus the {story_id}-th story                         | `{story_id} g`   |

| `goto_story_comment_view`      | Go the comment view associated with the focused story | `enter`          |

| `open_article_in_browser`      | Open in browser the focused story's article           | `o`              |

| `open_article_in_article_view` | Open in article view the focused story's article      | `O`              |

| `open_story_in_browser`        | Open in browser the focused story                     | `s`              |

| `next_page`                    | Go to the next page                                   | `n`              |

| `prev_page`                    | Go the previous page                                  | `p`              |

| `cycle_sort_mode`              | Cycle story sort mode                                 | `d`              |

#### Article View shortcuts

| Command                     | Description                            | Default Shortcut |

| --------------------------- | -------------------------------------- | ---------------- |

| `open_article_in_browser`   | Open article in browser                | `a`              |

| `open_link_in_browser`      | Open in browser {link_id}-th link      | `{link_id} o`    |

| `open_link_in_article_view` | Open in article view {link_id}-th link | `{link_id} O`    |

| `open_link_dialog`          | Open link dialog                       | `l`              |

##### Link dialog shortcuts

| Command                     | Description                           | Default Shortcut |

| --------------------------- | ------------------------------------- | ---------------- |

| `next`                      | Focus next link                       | `[j, down]`      |

| `prev`                      | Focus previous link                   | `[k, up]`        |

| `open_link_in_browser`      | Open in browser the focused link      | `[o, enter]`     |

| `open_link_in_article_view` | Open in article view the focused link | `O`              |

#### Comment View shortcuts

| Command                        | Description                                                                     | Default Shortcut |

| ------------------------------ | ------------------------------------------------------------------------------- | ---------------- |

| `next_comment`                 | Focus the next comment                                                          | `j`              |

| `prev_comment`                 | Focus the previous comment                                                      | `k`              |

| `next_leq_level_comment`       | Focus the next comment with smaller or equal level                              | `l`              |

| `prev_leq_level_comment`       | Focus the previous comment with smaller or equal level                          | `h`              |

| `next_top_level_comment`       | Focus the next top level comment                                                | `n`              |

| `prev_top_level_comment`       | Focus the previous top level comment                                            | `p`              |

| `parent_comment`               | Focus the parent comment (if exists)                                            | `u`              |

| `toggle_collapse_comment`      | Toggle collapsing the focused item                                              | `tab`            |

| `vote`                         | Toggle voting the focused item (**requires [authentication](#authentication)**) | `v`              |

| `open_article_in_browser`      | Open in browser the discussed article                                           | `a`              |

| `open_article_in_article_view` | Open in article view the discussed article                                      | `A`              |

| `open_story_in_browser`        | Open in browser the discussed story                                             | `s`              |

| `open_comment_in_browser`      | Open in browser the focused comment                                             | `c`              |

| `open_link_in_browser`         | Open in browser the {link_id}-th link in the focused comment                    | `{link_id} o`    |

| `open_link_in_article_view`    | Open in article view the {link_id}-th link in the focused comment               | `{link_id} O`    |

#### Search View shortcuts

In `SearchView`, there are two modes: `Navigation` and `Search`. The default mode is `Search`.

`Search` mode is similar to Vim's insert mode, in which users can input a query string.

`Navigation` mode allows the `SearchView` to behave like a `StoryView` of matched stories.

`SearchView`-specific key shortcuts:

| Command              | Description                                | Default Shortcut |

| -------------------- | ------------------------------------------ | ---------------- |

| `to_search_mode`     | Enter `Search` mode from `Navigation` mode | `i`              |

| `to_navigation_mode` | Enter `Navigation` mode from `Search` mode | ``          |

## Configuration

By default, `hackernews-tui` will look for the `hn-tui.toml` user-defined config file inside

- the [user's config directory](https://docs.rs/dirs-next/latest/dirs_next/fn.config_dir.html)

- `.config` directory inside the [user's home directory](https://docs.rs/dirs-next/latest/dirs_next/fn.home_dir.html)

If not found such file, the application will fall back to use a set of [default configurations](https://github.com/aome510/hackernews-TUI/blob/main/examples/hn-tui.toml).

User can also specify the path to config file when running the application with `-c` or `--config` option.

```shell

hackernews_tui -c ~/.config/hn-tui.toml

```

For further information about the application's configurations, please refer to the [example config file](https://github.com/aome510/hackernews-TUI/blob/main/examples/hn-tui.toml) and the [config documentation](https://github.com/aome510/hackernews-TUI/blob/main/config.md).

## Authentication

Users can authenticate their account by specifying `username` and `password` inside the `hn-auth.toml` file:

```toml

username=""

password=""

```

By default, the authentication file should be inside the same folder as the the general configuration file (`hn-tui.toml`), which can be configured by specifying the `-a` or `--auth` option.

## Logging

`hackernews-tui` uses `RUST_LOG` environment variable to define the application's [logging level](https://docs.rs/log/0.4.14/log/enum.Level.html) (default to be `INFO`).

By default, the application creates the `hn-tui.log` log file inside the [user's cache directory](https://docs.rs/dirs-next/latest/dirs_next/fn.cache_dir.html), which can be configured by specifying the `-l` or `--log` option.

## Roadmap

- [x] make all commands customizable

- [x] add a `View` to read the linked story in reader mode on the terminal. A list of possible suggestion can be found [here](https://news.ycombinator.com/item?id=26930466)

- [x] add commands to navigate parent comments and collapse a comment

- [x] make all the configuration options optional

- integrate [HackerNews Official APIs](https://github.com/HackerNews/API) for real-time updating, lazy-loading comments, and sorting stories

  - [x] lazy-loading comments

  - [x] front-page stories like the official site

  - [ ] real-time updating

- [x] implement smarter lazy-loading comment functionality

- add crediential support to allow

  - [x] authentication

  - [x] upvote/downvote

  - [ ] add comment

  - [ ] post

- improve application's UI

  - [x] improve the application's overall look

  - [x] include useful font-highliting

  - [x] rewrite the theme parser to support more themes and allow to parse themes from known colorschemes

  - [ ] add some extra transition effects

- improve the keybinding handler

  - [x] allow to bind multiple keys to a single command

  - [ ] add prefix key support (emacs-like key chaining - `C-x C-c ...`)