doc-reader

A keyboard-driven HTML reader for Markdown documents, with jumps into the Neovim instances you are editing them in. Markdown stays the only source: the server renders it on every request, and the page follows edits live.

• Nested, foldable sections (zM to an outline, l to drill in), Vim keys.
• Math (KaTeX), Mermaid diagrams, SVG/PNG figures, tables.
• n moves every running Neovim that has the file to the section you are reading; nvimd opens it when none has.
• q copies a question prompt for a coding agent; y copies a link.
• <leader>h in Neovim prints the reader URL of the section under the cursor.

Install

pip install nvim-doc-reader
docread serve

Requires Python 3.9+ and, for the editor features, Neovim 0.9+.

Configure

$XDG_CONFIG_HOME/doc-reader/config.toml (or $DOCREADER_CONFIG):

# Optional, with their defaults.
bind = "0.0.0.0"
port = 8765
public_url = "http://desknikos:8765"   # what `docread url` prints; default http://localhost:<port>
nvim = "nvim"
# nvim_socket_glob: default is where Neovim puts its own socket
# ($XDG_RUNTIME_DIR/nvim.*.0, else $TMPDIR/nvim.<user>/*/nvim.*.0)
state_file = "$XDG_STATE_HOME/doc-reader/last"
poll_interval_s = 0.5

# Which directories are served, by name. The name is part of the URL:
# /efs/nikos/notes/a.md  ->  /v/nikos/notes/a.md
# Default: the home directory, as "home".
[roots]
nikos = "/efs/nikos"

Every scalar key can be overridden with DOCREADER_<KEY>, and the roots with DOCREADER_ROOTS=name=/dir:name=/dir. Nested roots are fine: a file belongs to the most specific one, and any other URL for it redirects there.

Only files under a root are served. Raw files are served with Content-Security-Policy: sandbox, and raw HTML in Markdown is shown as text. There is no authentication: run it on a trusted network.

Keys

Neovim

n needs nothing in the editor: every Neovim listens on its own socket, and the server finds them by nvim_socket_glob. Windows showing the file move to the section; a buffer that is loaded but hidden moves when you next switch to it. nvimd with no arguments opens the last target; with arguments it is plain nvim.

For <leader>h:

vim.opt.rtp:append(vim.fn.trim(vim.fn.system({ "docread", "nvim-path" })))
require("doc_reader").setup({ cmd = { "docread" }, keymap = "<leader>h" })

Section IDs

A heading's ID is its explicit {#id} if it has one, otherwise GitHub's slug of its text, with -1, -2 for repeats. Give a section an explicit ID when links to it must survive a rename.

Agents

Documents written by coding agents read best when they follow a few rules: stable {#id}s, short overviews with depth in nested subsections, figures kept with their source, no fabricated data, and questions answered without editing. The rules ship as a Claude Code skill:

docread install-skill                 # -> ~/.claude/skills/doc-authoring/
docread install-skill --dir .claude/skills   # or per project

Then tell agents to use it, in your global ~/.claude/CLAUDE.md (or a project's CLAUDE.md):

## Writing Documents

Markdown documents you write for the user (research notes, reports, plans,
explainers) follow the `doc-authoring` skill — load it before creating or
editing one.

Other agents: if they read SKILL.md skills, point --dir at their skills directory; otherwise paste the skill's body into AGENTS.md / GEMINI.md.