reader.nvim

A distraction-free ebook reader for Neovim. Highlights the current paragraph and dims the rest. Supports .md, .txt, and .epub files.

Demo

reader.mp4

Features

• Paragraph-level focus highlighting with dimmed surroundings
• EPUB support with chapter navigation and table of contents
• Zen-mode style centered floating window layout
• Cursor auto-hides on blank lines between paragraphs
• User bookmarks with navigation (]b/[b) and picker (M)
• Inline notes as ghost text (select text, press n, type your note)
• Text highlighting with visual selection
• Remembers your reading position per file (chapter + line)
• EPUB parsing is cached for fast reopening
• Dictionary lookup with inline definitions (visual select + gd)
• Auto-scroll mode: word-by-word reading at configurable speed (g<Space>)
• Auto-open reader for configured filetypes
• Normal vim motions for navigation

Requirements

• Neovim >= 0.10
• termguicolors enabled (for cursor hiding)
• unzip command available (for EPUB support)

Installation

lazy.nvim

{
  "Sang-it/reader.nvim",
  cmd = "Reader",
  opts = {},
}

packer.nvim

use {
  "Sang-it/reader.nvim",
  config = function()
    require("reader").setup()
  end,
}

Usage

:Reader                  " Open current buffer file in reader mode
:Reader path/to/file     " Open a specific file
:ReaderClose             " Close reader mode (or press q)

" EPUB chapter navigation
:ReaderNext              " Next chapter
:ReaderPrev              " Previous chapter
:ReaderGo 5              " Jump to chapter 5
:ReaderToc               " Open table of contents picker

" Bookmarks
:ReaderMark              " Add a bookmark at current position
:ReaderMarks             " Show bookmarks picker
:ReaderMarkDelete        " Remove a bookmark

" Notes (displayed as ghost text)
:ReaderNote              " Add a note at current position
:ReaderNotes             " Show notes picker
:ReaderNoteDelete        " Remove a note

" Highlights (select text in visual mode)
:ReaderHighlights        " Show highlights picker
:ReaderHighlightDelete   " Remove a highlight

" Auto-scroll
:ReaderAutoScrollToggle  " Toggle word-by-word auto-scroll

Keybindings

All standard vim motions work (j, k, gg, G, Ctrl-d, Ctrl-u, /, etc.). The following are buffer-local bindings active in reader mode:

Key	Action
q	Close reader mode
]c	Next chapter (epub)
[c	Previous chapter (epub)
t	Table of contents (epub)
m	Add a bookmark
dm	Remove a bookmark
]b	Jump to next bookmark
[b	Jump to previous bookmark
M	Show bookmarks picker
n	Add a note at selection (visual mode)
dn	Remove a note
]n	Jump to next note
[n	Jump to previous note
N	Show notes picker
gn	Toggle notes visibility
s	Highlight selected text (visual mode)
ds	Remove a highlight
]s	Jump to next highlight
[s	Jump to previous highlight
S	Show highlights picker
gs	Toggle highlights visibility
gd	Dictionary lookup (visual mode)
g<Space>	Toggle auto-scroll mode

Configuration

require("reader").setup({
  -- Reading pane width in columns
  width = 80,

  -- Zen mode: centered floating window (true) or standard window (false)
  zen_mode = true,

  -- Highlight current paragraph and dim the rest in zen mode
  focus_paragraph = true,

  -- Center the focused paragraph in the viewport
  center_focus = true,

  -- Cursor hiding: "whitespace" (hide on blank lines), "always", or false
  hide_cursor = "whitespace",

  -- Show notes ghost text on open (toggle with gn)
  show_notes = true,

  -- Show text highlights on open (toggle with gs)
  show_highlights = true,

  -- Words per minute for auto-scroll mode (toggle with g<Space>)
  auto_scroll_wpm = 200,

  -- Number of words highlighted at a time during auto-scroll
  auto_scroll_words = 3,

  -- Pause at sentence endings (. ! ?) during auto-scroll
  auto_scroll_sentence_pause = false,

  -- Auto-open reader for these filetypes on BufEnter
  auto_open = {}, -- e.g. {"md", "txt", "epub"}

  -- Keybindings (set any to false to disable)
  keys = {
    quit = "q",
    toc = "t",
    next_chapter = "]c",
    prev_chapter = "[c",
    add_mark = "m",
    remove_mark = "dm",
    next_mark = "]b",
    prev_mark = "[b",
    list_marks = "M",
    add_note = "n",
    remove_note = "dn",
    next_note = "]n",
    prev_note = "[n",
    list_notes = "N",
    toggle_notes = "gn",
    add_highlight = "s",
    remove_highlight = "ds",
    next_highlight = "]s",
    prev_highlight = "[s",
    list_highlights = "S",
    toggle_highlights = "gs",
    dict_lookup = "gd",
    toggle_auto_scroll = "g ",
  },
})

How It Works

• Paragraph focus: A CursorMoved autocmd detects which paragraph the cursor is in and applies extmark highlights to dim everything else.
• EPUB parsing: EPUBs are unzipped via the system unzip command. Chapter structure comes from the NCX (EPUB2) or nav document (EPUB3) table of contents. Parsed content is cached to ~/.cache/nvim/reader.nvim/.
• Position memory: Reading position (chapter + line) is saved to ~/.local/share/nvim/reader.nvim/bookmarks.lua on close and restored on reopen.
• Layout: Uses two floating windows (a full-screen backdrop + a centered content window) for a clean, separator-free reading experience.