nvim-doc-reader 0.1.0__py3-none-any.whl

doc_reader/static/reader.js

@@ -0,0 +1,485 @@
+// doc-reader: keyboard reader over server-rendered nested <section>s.
+(() => {
+  "use strict";
+
+  const DATA = JSON.parse(document.querySelector("body > .dr-doc-data").textContent);
+  const docEl = document.querySelector("body > .dr-doc");
+  const outlineEl = document.querySelector("body > .dr-outline");
+  const bannerEl = document.querySelector("body > .dr-banner");
+  const toastEl = document.querySelector("body > .dr-toast");
+  const isDoc = DATA.kind === "doc";
+  const STORE_KEY = "doc-reader:" + (DATA.url || location.pathname);
+  const OUTLINE_KEY = "doc-reader:outline";  // one setting for every document
+  const tail = isDoc ? DATA.url.slice("/v/".length) : "";
+
+  let cur = null;
+  let version = DATA.version;
+
+  // ------------------------------------------------------------ structure
+  const sections = () => [...docEl.querySelectorAll("section")];
+  const heading = (s) => s.querySelector(":scope > .sec-h");
+  const parentSec = (s) => s.parentElement.closest("section");
+  const childSecs = (s) => [...s.querySelectorAll(":scope > section")];
+  const collapsed = (s) => s.classList.contains("collapsed");
+  const hasBody = (s) => [...s.children].some((c) => !c.classList.contains("sec-h"));
+  function hidden(s) {
+    for (let p = parentSec(s); p; p = parentSec(p)) if (collapsed(p)) return true;
+    return false;
+  }
+  const visible = () => sections().filter((s) => !hidden(s));
+  // Section IDs come from the document, so look only among its sections: a
+  // heading may be called anything, including what the page itself uses.
+  const byId = (id) =>
+    (id ? docEl.querySelector(`section[id="${CSS.escape(id)}"]`) : null);
+
+  // ------------------------------------------------------------ storage
+  function load() {
+    try { return JSON.parse(localStorage.getItem(STORE_KEY) || "{}"); } catch { return {}; }
+  }
+  function save() {
+    if (!isDoc) return;
+    const state = { collapsed: sections().filter(collapsed).map((s) => s.id),
+                    cur: cur && cur.id };
+    try { localStorage.setItem(STORE_KEY, JSON.stringify(state)); } catch { /* private mode */ }
+  }
+
+  // ------------------------------------------------------------ view
+  function inView(s) {
+    const r = heading(s).getBoundingClientRect();
+    return r.top >= 0 && r.bottom <= window.innerHeight;
+  }
+  function scrollToSec(s) {
+    const top = heading(s).getBoundingClientRect().top;
+    window.scrollTo({ top: window.scrollY + top - window.innerHeight * 0.15 });
+  }
+  function setCur(s, { scroll = true } = {}) {
+    if (cur) cur.classList.remove("cur");
+    cur = s;
+    if (s) {
+      s.classList.add("cur");
+      history.replaceState(null, "", "#" + s.id);
+      if (scroll && !inView(s)) scrollToSec(s);
+    }
+    markOutline();
+    save();
+  }
+  function fromViewport() {
+    const vis = visible();
+    let best = null;
+    for (const s of vis) {
+      if (heading(s).getBoundingClientRect().top <= window.innerHeight * 0.3) best = s;
+      else break;
+    }
+    return best || vis[0] || null;
+  }
+  function reveal(s) {
+    for (let p = parentSec(s); p; p = parentSec(p)) p.classList.remove("collapsed");
+  }
+  function collapse(s) {
+    if (!hasBody(s)) return;
+    s.classList.add("collapsed");
+    if (cur && hidden(cur)) setCur(s);
+    save();
+  }
+  function expand(s) {
+    s.classList.remove("collapsed");
+    renderMermaid(s);
+    save();
+  }
+  function goTo(id) {
+    const s = byId(id);
+    if (!s || s.tagName !== "SECTION") return;
+    reveal(s);
+    renderMermaid(docEl);
+    setCur(s, { scroll: false });
+    scrollToSec(s);
+  }
+
+  // ------------------------------------------------------------ outline
+  function buildOutline() {
+    if (!isDoc) { outlineEl.hidden = true; return; }
+    const build = (secs) => {
+      if (!secs.length) return "";
+      return "<ul>" + secs.map((s) =>
+        `<li><a href="#${s.id}" data-id="${s.id}">${escapeHtml(heading(s).textContent)}</a>` +
+        build(childSecs(s)) + "</li>").join("") + "</ul>";
+    };
+    outlineEl.innerHTML = build([...docEl.querySelectorAll(":scope > section")]);
+    markOutline();
+  }
+  function markOutline() {
+    outlineEl.querySelectorAll("a.cur").forEach((a) => a.classList.remove("cur"));
+    if (cur) {
+      const a = outlineEl.querySelector(`a[data-id="${CSS.escape(cur.id)}"]`);
+      if (a) { a.classList.add("cur"); a.scrollIntoView({ block: "nearest" }); }
+    }
+  }
+  function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;",
+                                           '"': "&quot;", "'": "&#39;" }[c]));
+  }
+
+  // ------------------------------------------------------------ math, diagrams
+  function renderMath(root) {
+    if (!window.katex) return;  // CDN unavailable: the TeX source stays readable
+    root.querySelectorAll(".math:not([data-done])").forEach((el) => {
+      try {
+        katex.render(el.textContent, el, { displayMode: el.dataset.display === "1",
+                                           throwOnError: false });
+      } catch { /* leave the source */ }
+      el.dataset.done = "1";
+    });
+  }
+  // Mermaid lays out wrong inside display:none, so diagrams render when their
+  // section is first visible.
+  async function renderMermaid(root) {
+    if (!window.mermaid) return;
+    const nodes = [...root.querySelectorAll("pre.mermaid:not([data-processed])")]
+      .filter((n) => n.offsetParent !== null);
+    if (!nodes.length) return;
+    try { await mermaid.run({ nodes, suppressErrors: true }); } catch { /* keep source */ }
+  }
+  if (window.mermaid) {
+    const dark = matchMedia("(prefers-color-scheme: dark)").matches;
+    mermaid.initialize({ startOnLoad: false, securityLevel: "strict",
+                         theme: dark ? "dark" : "default" });
+  }
+
+  // ------------------------------------------------------------ messages
+  let toastTimer = null;
+  function toast(msg) {
+    toastEl.textContent = msg;
+    toastEl.classList.add("show");
+    clearTimeout(toastTimer);
+    toastTimer = setTimeout(() => toastEl.classList.remove("show"), 2500);
+  }
+  function banner(msg) {
+    bannerEl.hidden = !msg;
+    bannerEl.textContent = msg || "";
+  }
+
+  // ------------------------------------------------------------ clipboard
+  // Plain http over the tailnet is not a secure context, so navigator.clipboard
+  // is usually missing; the textarea + execCommand route still works there.
+  function copyText(text, okMsg) {
+    const sel = window.getSelection();
+    const ranges = [];
+    for (let i = 0; i < sel.rangeCount; i++) ranges.push(sel.getRangeAt(i));
+    const ta = document.createElement("textarea");
+    ta.value = text;
+    ta.setAttribute("readonly", "");
+    ta.style.cssText = "position:fixed;top:0;left:0;opacity:0";
+    document.body.appendChild(ta);
+    ta.select();
+    let ok = false;
+    try { ok = document.execCommand("copy"); } catch { ok = false; }
+    ta.remove();
+    sel.removeAllRanges();
+    ranges.forEach((r) => sel.addRange(r));
+    if (ok) { toast(okMsg); return; }
+    if (navigator.clipboard && window.isSecureContext) {
+      navigator.clipboard.writeText(text).then(() => toast(okMsg), () => copyBox(text));
+    } else {
+      copyBox(text);
+    }
+  }
+  function copyBox(text) {
+    const box = overlay(`<p>Copy failed &mdash; select and copy by hand:</p>
+      <textarea readonly rows="10"></textarea>`);
+    const ta = box.querySelector("textarea");
+    ta.value = text;
+    ta.focus();
+    ta.select();
+  }
+  let overlayEl = null;
+  function overlay(inner) {
+    closeOverlay();
+    overlayEl = document.createElement("div");
+    overlayEl.className = "overlay";
+    overlayEl.innerHTML = `<div class="panel">${inner}<p class="dim">Esc to close</p></div>`;
+    overlayEl.addEventListener("click", (e) => { if (e.target === overlayEl) closeOverlay(); });
+    document.body.appendChild(overlayEl);
+    return overlayEl;
+  }
+  function closeOverlay() {
+    if (overlayEl) { overlayEl.remove(); overlayEl = null; }
+  }
+
+  // ------------------------------------------------------------ actions
+  function sectionUrl(s) {
+    return location.origin + location.pathname + (s ? "#" + s.id : "");
+  }
+  function question() {
+    const sel = window.getSelection();
+    const text = sel.toString().trim();
+    let s = cur;
+    if (text && sel.anchorNode) {
+      const el = sel.anchorNode.nodeType === 1 ? sel.anchorNode : sel.anchorNode.parentElement;
+      s = (el && el.closest("section")) || s;
+    }
+    const where = s
+      ? `section #${s.id} ("${heading(s).textContent.trim()}"), lines ${s.dataset.line}-${s.dataset.end}`
+      : "(whole document)";
+    const lines = [`Question about ${DATA.path} ${where}.`];
+    if (text) lines.push("Selected text:", text.split("\n").map((l) => "> " + l).join("\n"));
+    lines.push("Answer only. Do not edit any files. Afterwards, offer: integrate into the",
+               "section, attach as a nested subsection, or keep as a note.", "", "");
+    copyText(lines.join("\n"), "Question prompt copied — paste it into your agent");
+  }
+  async function openInNvim() {
+    const s = cur || fromViewport();
+    try {
+      const resp = await fetch("/api/open", {
+        method: "POST", headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ path: DATA.path, section_id: s ? s.id : null,
+                               line: s ? Number(s.dataset.line) : 1, version }) });
+      const r = await resp.json();
+      toast(r.message || (resp.ok ? "sent" : "failed"));
+    } catch (e) {
+      toast("Open in Neovim failed: " + e);
+    }
+  }
+
+  const HELP = [
+    ["j / k", "next / previous heading"],
+    ["h", "collapse, or go to parent"],
+    ["l", "expand, or go to first child"],
+    ["za zo zc", "toggle / open / close section"],
+    ["zO zC", "open / close section and everything in it"],
+    ["zM zR", "close all / open all"],
+    ["gg / G", "top / bottom"],
+    ["Ctrl-d / Ctrl-u", "half-page down / up"],
+    ["Tab, Enter", "focus and follow links"],
+    ["n", "open in Neovim (run nvimd if none has the file)"],
+    ["q", "copy a question prompt for your agent"],
+    ["y", "copy this section's link"],
+    ["o", "show / hide the outline"],
+    ["?", "this help"],
+  ];
+  function help() {
+    if (overlayEl) { closeOverlay(); return; }
+    overlay("<h2>Keys</h2><table>" + HELP.map(([k, d]) =>
+      `<tr><td><kbd>${k}</kbd></td><td>${d}</td></tr>`).join("") + "</table>");
+  }
+
+  // ------------------------------------------------------------ keys
+  function step(delta) {
+    const vis = visible();
+    if (!vis.length) return;
+    if (!cur || hidden(cur) || !inView(cur)) {
+      const s = fromViewport();
+      if (!cur || !inView(cur)) { setCur(s); return; }
+    }
+    const i = vis.indexOf(cur);
+    const next = vis[Math.min(vis.length - 1, Math.max(0, i + delta))];
+    if (next) setCur(next);
+  }
+  function setAll(fn) { sections().forEach(fn); }
+  function subtree(s) { return [s, ...s.querySelectorAll("section")]; }
+
+  const PREFIX = { g: { g: () => { const v = visible(); if (v.length) setCur(v[0], { scroll: false }); window.scrollTo({ top: 0 }); } },
+                   z: { a: () => cur && (collapsed(cur) ? expand(cur) : collapse(cur)),
+                        o: () => cur && expand(cur),
+                        c: () => cur && collapse(cur),
+                        O: () => cur && subtree(cur).forEach(expand),
+                        C: () => cur && [...subtree(cur)].reverse().forEach(collapse),
+                        M: () => {
+                          setAll((s) => hasBody(s) && s.classList.add("collapsed"));
+                          // A lone top-level section is the document title: closing it
+                          // would leave one line, so the outline starts one level down.
+                          const tops = [...docEl.querySelectorAll(":scope > section")];
+                          if (tops.length === 1) tops[0].classList.remove("collapsed");
+                          if (cur && hidden(cur)) {
+                            let s = cur;
+                            while (hidden(s)) s = parentSec(s);
+                            setCur(s);
+                          }
+                          save();
+                        },
+                        R: () => { setAll((s) => s.classList.remove("collapsed")); renderMermaid(docEl);
+                                   save(); if (cur) scrollToSec(cur); } } };
+  const KEYS = {
+    j: () => step(1),
+    k: () => step(-1),
+    h: () => {
+      if (!cur) return step(0);
+      if (hasBody(cur) && !collapsed(cur)) collapse(cur);
+      else if (parentSec(cur)) setCur(parentSec(cur));
+    },
+    l: () => {
+      if (!cur) return step(0);
+      if (collapsed(cur)) expand(cur);
+      else if (childSecs(cur).length) setCur(childSecs(cur)[0]);
+    },
+    G: () => { const v = visible(); if (v.length) setCur(v[v.length - 1], { scroll: false });
+               window.scrollTo({ top: document.body.scrollHeight }); },
+    n: () => openInNvim(),
+    q: () => question(),
+    y: () => copyText(sectionUrl(cur), "Link copied"),
+    o: () => {
+      const on = document.body.classList.toggle("show-outline");
+      try { localStorage.setItem(OUTLINE_KEY, on ? "1" : "0"); } catch { /* private mode */ }
+      if (on) markOutline();
+    },
+    "?": () => help(),
+  };
+
+  let pending = null, pendingTimer = null;
+  document.addEventListener("keydown", (e) => {
+    if (e.key === "Escape") { closeOverlay(); pending = null; return; }
+    const t = e.target;
+    if (t.closest && t.closest("input, textarea, select, [contenteditable]")) return;
+    if (e.altKey || e.metaKey) return;
+    if (e.ctrlKey) {
+      if (e.key === "d" || e.key === "u") {
+        e.preventDefault();
+        window.scrollBy({ top: (e.key === "d" ? 1 : -1) * window.innerHeight / 2 });
+        requestAnimationFrame(() => setCur(fromViewport(), { scroll: false }));
+      }
+      return;
+    }
+    if (overlayEl && e.key !== "?") return;
+    if (!isDoc && !"?".includes(e.key)) return;
+    if (pending) {
+      const fn = PREFIX[pending][e.key];
+      pending = null;
+      clearTimeout(pendingTimer);
+      if (fn) { e.preventDefault(); fn(); }
+      return;
+    }
+    if (PREFIX[e.key]) {
+      e.preventDefault();
+      pending = e.key;
+      pendingTimer = setTimeout(() => { pending = null; }, 1200);
+      return;
+    }
+    const fn = KEYS[e.key];
+    if (fn) { e.preventDefault(); fn(); }
+  });
+
+  // ------------------------------------------------------------ mouse
+  docEl.addEventListener("click", (e) => {
+    const h = e.target.closest(".sec-h");
+    if (!h || e.target.closest("a") || window.getSelection().toString()) return;
+    const s = h.parentElement;
+    collapsed(s) ? expand(s) : collapse(s);
+    setCur(s, { scroll: false });
+  });
+  outlineEl.addEventListener("click", (e) => {
+    const a = e.target.closest("a[data-id]");
+    if (!a) return;
+    e.preventDefault();
+    goTo(a.dataset.id);
+  });
+  window.addEventListener("hashchange", () => goTo(decodeURIComponent(location.hash.slice(1))));
+
+  // ------------------------------------------------------------ live reload
+  function snapshot() {
+    return { collapsed: sections().filter(collapsed).map((s) => s.id),
+             cur: cur && cur.id,
+             offset: cur ? heading(cur).getBoundingClientRect().top : null,
+             scrollY: window.scrollY };
+  }
+  function applyState(state) {
+    (state.collapsed || []).forEach((id) => { const s = byId(id); if (s && s.tagName === "SECTION") s.classList.add("collapsed"); });
+    const s = byId(state.cur);
+    cur = null;
+    if (s && s.tagName === "SECTION") { cur = s; s.classList.add("cur"); }
+  }
+
+  // One reload at a time; a version that arrives meanwhile is applied after,
+  // and every async step checks it is still the newest reload. The server
+  // announces each version once, so a fetch that fails is retried here
+  // (backing off) rather than waiting for the next edit.
+  let gen = 0, reloading = false, wanted = null, retryMs = 1000;
+  function onVersion(v) {
+    if (!v || v === version) return;
+    wanted = v;
+    if (!reloading) runReloads();
+  }
+  async function runReloads() {
+    reloading = true;
+    let failed = null;
+    try {
+      while (wanted && wanted !== version) {
+        const v = wanted;
+        wanted = null;
+        if (!(await reload())) { failed = v; break; }
+      }
+    } finally { reloading = false; }
+    if (failed) {
+      // Retry the newest version announced, which may have come in while the
+      // failed fetch was in flight (onVersion left it queued for this loop).
+      const v = wanted || failed;
+      wanted = null;
+      setTimeout(() => onVersion(v), retryMs);
+      retryMs = Math.min(retryMs * 2, 30000);
+    }
+  }
+  // False only for a failure worth retrying: the fetch itself.
+  async function reload() {
+    const my = ++gen;
+    const snap = snapshot();
+    let r;
+    try {
+      const resp = await fetch("/frag/" + tail, { cache: "no-store" });
+      if (!resp.ok) throw new Error("HTTP " + resp.status);
+      r = await resp.json();
+    } catch (e) { banner("Reload failed, retrying: " + e); return false; }
+    retryMs = 1000;
+    if (my !== gen) return true;
+    if (r.error) { banner("Render error, showing the last good version: " + r.error); return true; }
+    docEl.innerHTML = r.html;
+    version = r.version;
+    banner((r.warnings || []).join("; "));
+    if (r.title) document.title = r.title;
+    applyState(snap);
+    buildOutline();
+    renderMath(docEl);
+    await renderMermaid(docEl);
+    if (my !== gen) return true;
+    if (cur && snap.offset !== null) {
+      window.scrollTo({ top: window.scrollY + heading(cur).getBoundingClientRect().top - snap.offset });
+    } else {
+      window.scrollTo({ top: snap.scrollY });
+    }
+    save();
+    return true;
+  }
+
+  // Scrolling by mouse, PageDown or the scrollbar: once it settles, a current
+  // section that has left the screen gives way to the one being read, so `n`,
+  // `q` and `y` act on what is in front of you. One still on screen stays.
+  let scrollTimer = null;
+  window.addEventListener("scroll", () => {
+    clearTimeout(scrollTimer);
+    scrollTimer = setTimeout(() => {
+      if (!isDoc || (cur && heading(cur).getClientRects().length && onScreen(cur))) return;
+      setCur(fromViewport(), { scroll: false });
+    }, 150);
+  }, { passive: true });
+  function onScreen(s) {
+    const r = heading(s).getBoundingClientRect();
+    return r.bottom > 0 && r.top < window.innerHeight;
+  }
+
+  // ------------------------------------------------------------ start
+  if (isDoc) {
+    try {
+      if (localStorage.getItem(OUTLINE_KEY) === "1") document.body.classList.add("show-outline");
+    } catch { /* private mode */ }
+    if (DATA.error) banner("Render error: " + DATA.error);
+    else if (DATA.warnings && DATA.warnings.length) banner(DATA.warnings.join("; "));
+    const saved = load();
+    const hashId = decodeURIComponent(location.hash.slice(1));
+    applyState({ collapsed: saved.collapsed, cur: hashId || saved.cur });
+    buildOutline();
+    renderMath(docEl);
+    if (cur) { reveal(cur); requestAnimationFrame(() => scrollToSec(cur)); }
+    renderMermaid(docEl);
+    const es = new EventSource("/events/" + tail);
+    es.onmessage = (e) => onVersion(e.data);
+  } else {
+    outlineEl.hidden = true;
+  }
+})();

doc_reader/urls.py

@@ -0,0 +1,87 @@
+"""Filesystem path <-> reader URL, over named roots.
+
+    /efs/nikos/projects/ai/tasks/1/Task.md  ->  /v/nikos/projects/ai/tasks/1/Task.md
+
+The root's name is part of the URL, so two roots holding the same relative
+path cannot shadow each other. A file under several (nested) roots belongs to
+the most specific one; that is its canonical URL, and any other spelling of it
+-- through the outer root, or through a symlink -- redirects there, so one
+file has one URL (and one saved reading position).
+"""
+import os
+from urllib.parse import quote, unquote, urlsplit
+
+PREFIX = "/v/"
+
+
+class Roots:
+  def __init__(self, roots):
+    """`roots`: name -> directory (already expanded)."""
+    self.roots = {name: os.path.realpath(path) for name, path in roots.items()}
+
+  def canonical(self, path):
+    """(name, relative path) of `path`'s real location, or None when it is
+    outside every root."""
+    real = os.path.realpath(path)
+    best = None
+    for name, root in self.roots.items():
+      if real == root or real.startswith(root.rstrip("/") + "/"):
+        if best is None or len(root) > len(self.roots[best]):
+          best = name
+    if best is None:
+      return None
+    root = self.roots[best]
+    return best, "" if real == root else os.path.relpath(real, root)
+
+  def url_path(self, path):
+    """`/v/<name>/<rel>` for a file or directory, or None outside the roots."""
+    found = self.canonical(path)
+    if found is None:
+      return None
+    name, rel = found
+    url = PREFIX + quote(name) + "/" + quote(rel)
+    if os.path.isdir(path) and not url.endswith("/"):
+      url += "/"
+    return url
+
+  def resolve(self, url_path):
+    """The real path behind `/v/<name>/<rel>`, or None if the name is unknown
+    or the path escapes its root (`..`, a symlink pointing out)."""
+    if not url_path.startswith(PREFIX):
+      return None
+    name, _, rel = url_path[len(PREFIX):].partition("/")
+    root = self.roots.get(unquote(name))
+    if root is None:
+      return None
+    real = os.path.realpath(os.path.join(root, unquote(rel)))
+    if real != root and not real.startswith(root.rstrip("/") + "/"):
+      return None
+    return real
+
+  def link_rewriter(self, doc_path):
+    """For links inside the document at `doc_path`: local targets resolved
+    against the document's REAL directory and mapped to canonical URLs, with
+    query and fragment kept; None for local targets outside every root;
+    anything with a scheme, or a bare `#fragment`, unchanged."""
+    base = os.path.dirname(os.path.realpath(doc_path))
+
+    def rewrite(href):
+      if not href or href.startswith("#"):
+        return href
+      parts = urlsplit(href)
+      if parts.scheme or parts.netloc:
+        return href
+      target = unquote(parts.path)
+      if not target:
+        return href
+      target = target if os.path.isabs(target) else os.path.join(base, target)
+      url = self.url_path(target)
+      if url is None:
+        return None
+      if parts.query:
+        url += "?" + parts.query
+      if parts.fragment:
+        url += "#" + parts.fragment
+      return url
+
+    return rewrite

nvim_doc_reader-0.1.0.dist-info/METADATA

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: nvim-doc-reader
+Version: 0.1.0
+Summary: Keyboard-driven HTML reader for Markdown docs, with jumps into running Neovim
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: markdown-it-py<3,>=2.1
+Requires-Dist: mdit-py-plugins<0.4,>=0.3.4
+Requires-Dist: aiohttp>=3.8
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+
+# 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
+
+```bash
+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`):
+
+```toml
+# 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
+
+| key | action |
+|---|---|
+| `j` / `k` | next / previous heading |
+| `h` / `l` | collapse or go to parent / expand or go to first child |
+| `za` `zo` `zc` `zO` `zC` | toggle / open / close / open all inside / close all inside |
+| `zM` / `zR` | close all / open all |
+| `gg` / `G`, `Ctrl-d` / `Ctrl-u` | top / bottom, half page |
+| `Tab`, `Enter` | focus and follow links |
+| `n` | open in Neovim |
+| `q` | copy a question prompt |
+| `y` | copy the section's link |
+| `o` | show / hide the outline |
+| `?` | help |
+
+## 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`:
+
+```lua
+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:
+
+```bash
+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`):
+
+```markdown
+## 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`.