scroll

A terminal markdown reader with multi-column layout, real link navigation, inline images, and ASCII-art mermaid diagrams.

Status: early. Core viewer is solid and used daily; the repo is still settling — release tags, install paths, and the public Go API surface are still moving. See docs/roadmap.md for what's pending.

Why scroll?

Built for reading long-form docs in a terminal, with the things that workflow needs:

• Multi-column "newspaper" layout on wide terminals.
• Real link navigation — Tab to cycle, Enter to follow, Ctrl+O / Ctrl+I for back/forward.
• HJKL heading-tree navigation, jump-to-heading picker, fuzzy file picker, RE2-regex search, heading-tree folding.
• Inline image impressions — coloured Unicode block glyphs that read as a recognisable thumbnail without needing a graphics protocol. Pixel-accurate Kitty rendering is available as an experimental opt-in.
• Mermaid diagrams as Unicode box-drawing via termaid.
• Live reload, per-file scroll-position memory, TOML themes with a template DSL for custom decoration.

Install

Needs Go 1.25.9+.

Latest from source:

go install github.com/rynobey/scroll@latest

From a release (linux amd64/arm64, darwin amd64/arm64): download the right scroll-<tag>-<os>-<arch>.tar.gz from the releases page, extract, drop scroll somewhere on $PATH. Each archive ships the binary plus LICENSE and README.md. SHA-256 checksums are published as checksums.txt alongside the archives.

Build from source:

git clone https://github.com/rynobey/scroll
cd scroll
make build              # produces ./scroll
make release            # bin/scroll-{linux,darwin}-{amd64,arm64}

Usage

scroll README.md             # interactive viewer
scroll --static README.md    # render to stdout, exit
cat foo.md | scroll -        # stdin (works for both modes)
scroll --print-theme         # dump the effective theme as TOML

Flags (use -- or single -; both work):

Flag	What it does
--static	render and print, don't launch viewer
--width N	force content width (default: terminal width)
--theme NAME	built-in: default, compact, minimal
--config PATH	theme config TOML (default: ~/.config/scroll/config.toml)
--print-theme	dump the effective theme as TOML and exit
--debug-dump	dump canvas rows with line numbers, no styling

Common keybindings (full list under ? in the viewer):

Key	Action
j/k, space/b, g/G	scroll line / page / top-bottom
Tab / Shift+Tab	cycle focused link
Enter	follow link
Ctrl+O / Ctrl+I	back / forward in link history
J / K	next / previous same-level heading
L / H	next deeper / previous shallower heading
Space	jump-to-heading picker
/, n, N	search forward, next match, previous match
za, zM, zR	toggle / close-all / open-all folds
?	help overlay
q	quit

Configuration

Put a TOML config at ~/.config/scroll/config.toml (or pass --config PATH). Every field is optional — the built-in theme fills in anything you don't set.

Two starting points:

• examples/config.toml.example — a curated copy-and-tweak file with every knob present.
• scroll --print-theme > ~/.config/scroll/config.toml — dumps the fully resolved theme as TOML; useful when you want to tweak from defaults without comments in the way.

Switch built-in themes with --theme default|compact|minimal.

The schema, the template DSL, worked examples, and a recipe book live in docs/configuration.md.

Inline images

What "image rendering" means here. scroll's default rendering paths approximate an image as a grid of coloured Unicode block characters. The result is a recognisable impression — you can tell what the picture is of and follow the gist — but it's not pixel-accurate; sub-pixel detail and small text in images won't survive the round-trip. Real graphics-protocol rendering needs Kitty / Sixel / iTerm; only Kitty is wired in today and is experimental.

scroll auto-detects the best impression-rendering path on the current terminal:

1. FineBlocks — 3×5 sub-pixel grid via a custom PUA-patched font. The highest-fidelity impression path. Requires installing one font; see docs/fine-blocks.md.
2. Blocks — Unicode quadrant + sextant glyphs with truecolor SGR. Works on every modern terminal. Default when the patched font isn't installed.
3. None — text placeholder ([image: alt]) when truecolor isn't available.

For pixel-accurate rendering on Kitty / WezTerm / Ghostty, opt into the experimental Kitty path with SCROLL_IMG_PROTO=kitty,fineblocks,blocks.

Mermaid diagrams

Install termaid and any ```mermaid block renders as Unicode box-drawing text. No Chromium dependency, no graphics protocol required.

go install github.com/fasouto/termaid@latest

When termaid isn't installed, mermaid blocks fall through to syntax-highlighted source.

Neovim integration

nvim/ ships scroll.nvim: a floating-window markdown preview that runs scroll in a real PTY so the interactive viewer (link nav, search, folds, multi-column) works inside neovim. Saving the buffer auto-refreshes the preview.

The plugin lives inside this repo under nvim/ rather than at the root, so plugin managers can't auto-install it via the github short-form. Clone the repo somewhere stable, then point your plugin manager at the nvim/ subdirectory:

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

-- lazy.nvim
{
    dir = vim.fn.expand("~/.local/share/scroll-source/nvim"),
    name = "scroll.nvim",
    config = function()
        require("scroll").setup({})
        vim.keymap.set("n", "<leader>mp", function()
            require("scroll").preview()
        end, { desc = "Markdown preview (scroll)" })
    end,
}

See nvim/README.md for the configuration schema, behaviour notes, and the in-tree-vs-separate-repo plan.

Troubleshooting

Images render as boxes / ? characters. The patched fineblocks font isn't visible to your terminal. Verify with fc-match :charset=100001 family (should print … Scroll). Re-run the steps in docs/fine-blocks.md, or unset the fineblocks path with SCROLL_IMG_PROTO=blocks to fall back to Unicode quadrant rendering.

Mermaid blocks render as syntax-highlighted source instead of diagrams. Install termaid (above). Confirm with which termaid.

Colours look washed out / wrong. scroll picks truecolor based on $COLORTERM / $TERM. Set COLORTERM=truecolor if your terminal supports 24-bit colour but doesn't advertise it.

URL link Enter does nothing on macOS / Windows. scroll shells out to xdg-open, which is Linux-only. Until that's fixed (see roadmap), copy the URL by hand.

go install hangs / fails. Verify your GOPROXY resolves public modules. Some corporate proxies block golang.org/x/* or honnef.co/go/tools — work around with GOPROXY=https://proxy.golang.org,direct.

Multi-column layout doesn't kick in. It only activates when the terminal is wide enough that columns × max_width + gutters fits. Either widen the terminal, lower max_width, or set columns = 1 to force single-column.

Documentation

• docs/cheatsheet.md — one-page quick reference: CLI flags, keybindings, DSL tokens, env vars.
• docs/ — architecture, configuration knobs, keybindings, image-rendering details, and the pending-work roadmap. Start at docs/README.md for an index.
• CHANGELOG.md — version history.
• CONTRIBUTING.md — how to build, test, and submit changes.
• SECURITY.md — how to report vulnerabilities privately.

License

MIT. Each release archive bundles a third_party/ directory containing the licence file from every Go module scroll's binary links against.