preetjdp/hackernews-TUI

A Terminal UI to browse Hacker News

hackernews-TUI

hackernews_tui is a fast and customizable application for browsing Hacker News on the terminal.

hackernews_tui is written in Rust with the help of Cursive TUI library. It uses HN Algolia APIs and HN Official APIs to get Hacker News data.

Table of Contents

• Install
  • Binaries
  • Using Cargo
  • Docker Image
  • Building from source
  • macOS
  • Arch Linux
  • NetBSD
• Examples
  • Demo
• Default Shortcuts
  • Global key shortcuts
  • Edit key shortcuts
  • Key shortcuts for each View
    • Story View
    • Article View
    • Comment View
    • Search View
• Configuration
• Authentication
• Logging
• Roadmap

Install

Binaries

Application's prebuilt binaries can be found in the Releases Page.

Using cargo

Install the latest version from crates.io by running cargo install hackernews_tui.

Docker image

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

docker pull aome510/hackernews_tui:latest

then run

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

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

git clone https://github.com/aome510/hackernews-TUI.git
cd hackernews-TUI
cargo build --release

to build the application, then run

./target/release/hackernews_tui

to run the application, or

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

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

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

pkgin install hackernews-tui

Building from source

cd /usr/pkgsrc/www/hackernews-tui
make install

Examples

Demo

Demo videos of hackernews_tui v0.9.0 are available on youtube and asciinema

Story View

Article View

Search View

Comment View

Default Shortcuts

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

The below sections will list the application's default shortcuts, which can be customized by changing the key mappings 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.

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)	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	<esc>

Configuration

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

• the user's config directory
• .config directory inside the user's home directory

If not found such file, the application will fall back to use a set of default configurations.

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

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

For further information about the application's configurations, please refer to the example config file and the config documentation.

Authentication

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

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 (default to be INFO).

By default, the application creates the hn-tui.log log file inside the user's cache directory, which can be configured by specifying the -l or --log option.

Roadmap

• make all commands customizable
• add a View to read the linked story in reader mode on the terminal. A list of possible suggestion can be found here
• add commands to navigate parent comments and collapse a comment
• make all the configuration options optional
• integrate HackerNews Official APIs for real-time updating, lazy-loading comments, and sorting stories
  • lazy-loading comments
  • front-page stories like the official site
  • real-time updating
• implement smarter lazy-loading comment functionality
• add crediential support to allow
  • authentication
  • upvote/downvote
  • add comment
  • post
• improve application's UI
  • improve the application's overall look
  • include useful font-highliting
  • 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
  • allow to bind multiple keys to a single command
  • add prefix key support (emacs-like key chaining - C-x C-c ...)