vim-hackernews

Browse Hacker News inside Vim.

Uses the official Hacker News Firebase API to retrieve stories, items, and comments, and FUCK YEAH MARKDOWN for rendering HTML articles as text.

Basic Usage

• Open the Hacker News front page in Vim by executing the :HackerNews command
• The HackerNews command takes an optional parameter to view other lists:
  • :HackerNews ask
  • :HackerNews show
  • :HackerNews jobs
  • :HackerNews best
  • :HackerNews newest
  • (default is the front page/top stories)
• Press lowercase o to open links in Vim
• Press uppercase O to open links in default web browser
• Numbered lines with story titles on the front page link to the story url
• Comment lines on the front page link to the comments url
• Press uppercase F to fold current comment thread
• Press lowercase u to go back
• Press Ctrl+r to go forward
• Execute the :bd command to close and remove the Hacker News buffer

Extra Commands

• :HackerNewsRefresh — clears the current Hacker News buffer and refetches the active list from the official API.
• :HackerNewsCopyLinks — copies all http/https links visible in the current Hacker News buffer to your system clipboard (and unnamed register), one per line.

Why the switch to the Official API?

We switched from a third-party API to the official Hacker News Firebase API to improve reliability and reduce external dependencies.

• Reliability: avoids frequent outages/timeouts seen with the previous API.
• Accuracy: works directly with canonical HN items and comment trees.
• Transparency: public, well-documented endpoints maintained by HN.

Note: fetching deep comment trees can be slower because the official API requires multiple requests. The plugin shows progress messages by default (g:hackernews_show_progress) so you can see what’s happening.

Configuration

• g:hackernews_show_progress (default: 1)

  • Show short progress messages while fetching stories/items and building comment trees. Set to 0 to silence messages.

• g:hackernews_max_items

  • Max stories fetched per list. Defaults to ~60 for top/newest/best, ~30 for others.

• g:hackernews_concurrency

  • Number of parallel requests when fetching story details from the official API. Default 12.

Performance

This plugin uses the official API, which returns lists of story IDs. To keep loads fast, vim-hackernews fetches story details in parallel:

• Threaded fetch: a small thread pool (default 12 threads) pulls items by ID. Python threads are appropriate here because HTTP I/O releases the GIL.
• Ordered output: results are reassembled in the original ID order.
• Batching feedback: progress messages are printed every 10 items.
• Tunable limits: g:hackernews_max_items controls how many stories are fetched per list; g:hackernews_concurrency controls the thread pool size.
• Comment trees: still fetched recursively, with sensible internal limits to avoid timeouts on very large threads; progress shown for top-level fetches.

Trade-offs:

• Higher concurrency improves latency on fast networks, but can trip rate caps or saturate slow links. If you see timeouts, lower g:hackernews_concurrency or g:hackernews_max_items.

Tuning Tips

Use these quick presets in your vimrc based on your environment:

• Slow connection / VPN

  • let g:hackernews_max_items = 30
  • let g:hackernews_concurrency = 6

• Typical laptop on home/office Wi‑Fi

  • let g:hackernews_max_items = 60 (default)
  • let g:hackernews_concurrency = 12 (default)

• Fast wired network / powerful desktop

  • let g:hackernews_max_items = 90
  • let g:hackernews_concurrency = 24

Notes:

• If you encounter occasional timeouts, try reducing concurrency first.
• Increasing the max items will usually have more impact on total time than increasing concurrency.

Demo

We plan to include a short demo GIF showing progress messages while loading stories and comments.

• Placeholder path for the GIF: screenshots/demo-progress.gif

• If you want to record one now, here are two common approaches:

  1. Asciinema + agg (SVG/GIF)

     • Install: pip install asciinema svg-term-cli and npm i -g agg (or use your package manager equivalents).
     • Record: asciinema rec demo.cast --command "vim -Nu NONE -c 'set rtp+=.' -c 'let g:hackernews_show_progress=1' -c 'HackerNews'"
     • Convert: agg demo.cast screenshots/demo-progress.gif --theme solarized-dark --font-size 14 --width 120 --fps 15

  2. GUI recorder (Peek, Kap, etc.)

     • Open a terminal at least 120x35 chars.
     • Run: vim -Nu NONE -c 'set rtp+=.' -c 'let g:hackernews_show_progress=1' -c 'HackerNews'
     • Start recording before running :HackerNews and stop once the list appears and progress messages complete.

Tip: Ensure let g:hackernews_show_progress=1 so messages are visible.

Enhanced Motions

Uppercase J and K are mapped to helpful new motions based on what type of content is on the screen:

• Move to next/prev item when viewing the front page. (If the cursor is on a numbered line with story title the cursor will move to the next/prev numbered line with story title. If the cursor is on a comment line it will move to the next/prev comment line.)
• Move to next/prev comment when viewing comments.
• Move to next/prev paragraph when viewing the text version of articles.

Installation

Pathogen (https://github.com/tpope/vim-pathogen)

git clone https://github.com/ryanss/vim-hackernews ~/.vim/bundle/vim-hackernews

Vundle (https://github.com/gmarik/vundle)

Plugin 'ryanss/vim-hackernews'

NeoBundle (https://github.com/Shougo/neobundle.vim)

NeoBundle 'ryanss/vim-hackernews'

Running Tests

Vim integration tests use Vader.vim.

$ git clone https://github.com/junegunn/vader.vim
$ vim -Nu NONE \
      -c 'set rtp+=./vader.vim' \
      -c 'set rtp+=.' \
      -c 'Vader! tests.vader' \
      -c 'qa!'

Python unit tests (no Vim required):

1. Create and activate a virtual environment (recommended by macOS/Homebrew):

   $ python3 -m venv .venv
   $ source .venv/bin/activate

2. Bring the tools in via pip:

   (.venv) $ python -m pip install pytest coverage

3. Run the Python unit tests (no Vim required):

   (.venv) $ pytest tests/test_hackernews.py

4. Generate a coverage report for the Python module:

   (.venv) $ coverage run -m pytest tests/test_hackernews.py
   (.venv) $ coverage report

Contributions

Issues and Pull Requests are always welcome!

License

Code is available according to the MIT License (see LICENSE).