nvim

scroll.nvim

Neovim integration for scroll, the terminal markdown viewer.

A floating-window preview that opens the current markdown buffer in scroll inside a real PTY, so the interactive viewer (link navigation, search, folds, column switch) works live. Saving the underlying buffer refreshes the preview automatically — scroll watches the file's mtime.

Requirements

• Neovim 0.9+
• scroll on $PATH (go install github.com/rynobey/scroll@latest, or a binary from the releases page)

Install

The plugin currently lives inside the main scroll repo under nvim/. Plugin managers expect lua/ at the cloned repo's root, so auto-install via the github short-form ("rynobey/scroll") won't pick the plugin up. The install recipes below clone the repo manually and point your plugin manager at the nvim/ subdirectory. A future v0.2+ may split the plugin to its own rynobey/scroll.nvim repo for cleaner install — see Future below.

lazy.nvim (manual clone, then dir =)

Clone the repo somewhere stable:

git clone https://github.com/rynobey/scroll ~/.local/share/scroll-source

Point lazy.nvim at the nvim/ subdirectory:

{
    dir = vim.fn.expand("~/.local/share/scroll-source/nvim"),
    name = "scroll.nvim",
    config = function()
        require("scroll").setup({
            preview = {
                -- Optional: path to a scroll config.toml.
                -- config_path = vim.fn.stdpath("config") .. "/scroll-preview.toml",
                -- border_color = "#ffaf5f",
                -- width_frac = 0.9,
            },
        })
        vim.keymap.set("n", "<leader>mp", function()
            require("scroll").preview()
        end, { desc = "Markdown preview (scroll)" })
    end,
}

dir makes lazy.nvim treat the local path as a managed plugin without trying to clone it itself.

packer.nvim or any manager that supports rtp = ...

Same idea — clone manually, then add the subdir to the runtimepath.

Without a plugin manager

vim.opt.rtp:prepend("/path/to/scroll/nvim")
require("scroll").setup()
vim.keymap.set("n", "<leader>mp", function()
    require("scroll").preview()
end, { desc = "Markdown preview (scroll)" })

Config

require("scroll").setup({
    preview = {
        border_color = "#ffaf5f",   -- hex; border highlight
        config_path  = nil,          -- path to scroll config.toml (nil = scroll default)
        width_frac   = 0.9,          -- fraction of editor columns when cols >= 80
    },
})

See examples/nvim-preview.toml for a ready-to-use preview theme (distinct status-bar colour so the float reads as a separate overlay).

Behaviour notes

• Mouse is disabled for the duration of the float so keystrokes land in scroll's terminal rather than dropping nvim into visual mode.
• Inside tmux, allow-passthrough is enabled for the lifetime of the preview so scroll's Kitty image-protocol escapes reach the outer terminal, then restored on close.
• Re-entering the float via focus/window change automatically returns to terminal-mode so keys like q quit scroll.

Future

The "in-tree vs separate repo" question is open. In-tree wins on coupling — the plugin and the binary are versioned and released together. Separate repo wins on ergonomics — install becomes a one-liner with any plugin manager.

Decision for v0.1.0: in-tree. The plugin is small (~150 lines of Lua), ships behind one keybinding, and has zero external Lua dependencies. The install awkwardness is documented above. If usage picks up enough for the install friction to matter, splitting to rynobey/scroll.nvim is roughly a half-day of work (move files, mirror the CHANGELOG, add a go install reference for the binary).

Changelog

See CHANGELOG.md for the plugin-specific version history. The main scroll binary's changelog is in ../CHANGELOG.md; the plugin's lock-step matches the binary's tags.