mdview.nvim · View & render · vimdoc

:help mdview

Browser-based Markdown preview for Neovim

doc/mdview.txt — rendered from the plugin's own vimdoc

*mdview.txt*  Browser-based Markdown preview for Neovim          *mdview.nvim*

CONTENTS *mdview-contents*

  1. Introduction ............................................. |mdview-intro|
  2. Requirements ...................................... |mdview-requirements|
  3. Installation ...................................... |mdview-installation|
  4. Configuration ........................................... |mdview-config|
  5. Commands .............................................. |mdview-commands|
  6. Autocommands .......................................... |mdview-autocmds|
  7. Keymaps ................................................ |mdview-keymaps|
  8. Health check ............................................ |mdview-health|
  9. Architecture ...................................... |mdview-architecture|
 10. Security model ........................................ |mdview-security|
 11. Background & standalone ........................... |mdview-standalone|

1. INTRODUCTION *mdview-intro*

mdview.nvim renders the current Markdown buffer live in a browser tab.

It syncs both ways: the editor drives the browser (text, scroll, cursor,
selection), and the browser writes back into the buffer -- click a block to edit
its Markdown source (:MDView edit), tick a task-list checkbox, type into a text
field. Edits from the browser are one undo step, wait while you type in Insert
mode, arrive in order, and are refused (never overwriting) when the text changed
under them.

A small Go relay process streams raw buffer text to the browser over
WebSocket. Rendering and HTML sanitization happen entirely client-side, in a
Rust module compiled to WebAssembly (comrak for Markdown -> HTML, ammonia for
allowlist-based sanitization). The relay never touches HTML — it only ever
transports the raw text and the already-sanitized-in-the-browser output never
leaves the browser again. See |mdview-security| for the full threat model.

No Node.js, Go or Rust toolchain is required to run the plugin. The relay
binary and the browser client bundle are fetched once from GitHub Releases on
first use and cached under |stdpath('data')|, the same pattern mason.nvim and
nvim-treesitter use for external binaries.

2. REQUIREMENTS *mdview-requirements*

  - Neovim 0.9 or later
  - lib.nvim (https://github.com/WKDSteve/lib.nvim) — hard dependency,
    used for cross-platform helpers (path normalization, OS detection,
    user command / autocmd registration wrappers)
  - curl on PATH — downloads the relay binary and client bundle
  - tar on PATH — extracts the downloaded client bundle
    (bundled with Windows 10 1803+, macOS and virtually every Linux distro)

Run |:checkhealth-mdview| to verify all of the above on your system.

3. INSTALLATION *mdview-installation*

lazy.nvim, lazy-loaded on markdown files or the plugin's own commands
(recommended):

  {
    "WKDSteve/mdview.nvim",
    dependencies = { "WKDSteve/lib.nvim" },
    ft  = { "markdown" },
    cmd = { "MDView" },
    config = function()
      require("mdview").setup()
    end,
  }
lazy.nvim, eager (loads at startup instead of on demand):

  {
    "WKDSteve/mdview.nvim",
    dependencies = { "WKDSteve/lib.nvim" },
    lazy = false,
    config = function()
      require("mdview").setup()
    end,
  }
packer.nvim:

  use {
    "WKDSteve/mdview.nvim",
    requires = { "WKDSteve/lib.nvim" },
    ft  = { "markdown" },
    cmd = { "MDView" },
    config = function()
      require("mdview").setup()
    end,
  }
No external toolchain is required by end users — the relay binary and client
bundle download automatically the first time |:MDView-start| runs.

4. CONFIGURATION *mdview-config*

                                                            *mdview.setup()*
Call require("mdview").setup({opts}) from your plugin manager's config
function. All defaults live in a single typed table in
lua/mdview/config/DEFAULTS.lua; setup() deep-merges your overrides into it
in place, so a partial nested override (e.g. only browser.browser) never
wipes out the rest of that sub-table's defaults.

Defaults:

  {
    ft_pattern = { "*.md", "*.markdown", "*.mdx" },
    any_file   = false,   -- preview any normal text buffer, not just Markdown

    server_port     = 43219,  -- preferred port for the relay server
    server_cwd      = nil,    -- optional explicit cwd for the relay process
    dev_server_port = 43220,  -- Vite dev server port (dev workflow only)

    dev_local       = true,
    debug           = false,  -- echo relay stdout/stderr into Neovim
    log_buffer_name = "mdview://logs",
    file_log        = false,  -- opt in to writing the relay log to a file
    file_log_path   = nil,    -- default: stdpath('log')/mdview/relay-<ts>.log
    debug_plugin    = false,  -- plugin-internal debug notifications
    debug_preview   = false,  -- per-push debug notifications (noisy)

    scroll_sync             = true, -- nvim-to-browser cursor-follow scroll
    scroll_sync_throttle_ms = 150,  -- min. time between scroll-position pings

    breadcrumbs             = true, -- record session breadcrumbs
                                    -- (:MDView breadcrumbs)

    sync_checkboxes         = true, -- ticking a task-list checkbox in the
                                    -- preview writes back to the source
    sync_fields             = true, -- editing an <input name>/<textarea name>
                                    -- in the preview writes its value back
    edit_blocks             = false, -- click a block in the preview to edit
                                    -- its source lines (:MDView edit)
    keymaps                 = {},    -- opt-in, e.g. { write = "<leader>mw" }
                                    -- (:MDView write toggle); none by default

    open_preview_tab = false, -- :MDView start opens an nvim tab, not a browser

    shared_relay = {          -- one relay + one tab for all nvim instances
      enabled        = false, -- opt-in; needs a relay newer than v0.4.3
      heartbeat_ms   = 2000,  -- how often an instance reports to the relay
      idle_timeout_s = 30,    -- silent this long = gone; none left = relay ends
    },

    browser = {
      open_mode           = "default", -- "default" (tab in your browser)
                                       -- | "isolated" (own window, auto-close)
      behavior            = "reuse",   -- on buffer switch: "reuse" (one tab
                                       -- follows) | "new_tab" | "manual"
      theme               = "github",  -- github|dark-dimmed|plain|tokyonight|
                                       -- catppuccin (optionally -light/-dark)
      highlighter         = "hljs",    -- code highlighter: hljs|shiki|nvim|none
      external_links      = "new_tab", -- external links: "new_tab" | "same_tab"
      cursor_marker       = "line",    -- "line"|"caret"|"block"|"section"|"off"
      cursor_blink        = false,     -- block marker: false | true | { ms = 530 }
      cursor_paragraph    = false,     -- tint the block under the cursor
      selection_sync      = false,     -- mirror the visual selection (v/V/C-v)
      spotlight_sync      = true,      -- mirror spotlight.nvim's highlights
      spotlight_max_matches = 500,     -- matches painted per spotlight
      display_lang        = nil,       -- preview in another language, e.g. "en" (:MDView lang)
      zoom                = 1.0,       -- preview font-size zoom (:MDView zoom)
      overlays            = {          -- preview overlays (:MDView overlay)
        toc = false,                   -- floating outline, current section lit
        keycast = false,               -- the keys pressed in Neovim (needs ui.nvim)
      },
      keycast             = {          -- what the keycast overlay shows
        scope = "normal",              -- "normal"|"insert_protected"|"all"
      },
      focus               = "browser", -- "browser" | "nvim" (keep editor focus)
      autodetect_browser  = true,  -- isolated mode only
      browser             = "",    -- friendly name, e.g. "firefox" (isolated)
      browser_cmd         = "",    -- absolute path (isolated mode only)
      browser_autoclose   = true,  -- :MDView stop closes the tab (isolated only)
      browser_autostart   = true,  -- open the browser on :MDView start
      browser_args        = nil,   -- extra CLI args (isolated mode only)
      open_url            = nil,   -- static URL override (advanced)
      require_display     = true,  -- skip browser without GUI/DISPLAY
      stop_on_browser_exit = true, -- browser closed => :MDView stop (isolated)
    },

    start = {
      push_strategy    = "launcher", -- "launcher" | "try_push"
      try_push_opts    = nil,
      wait_timeout_ms  = nil,
    },

    install = {
      repo    = "WKDSteve/mdview.nvim", -- override to use a fork
      version = "v0.4.3",                  -- pin a specific release tag
    },

    standalone = {
      binary_path = nil, -- relay used by :MDView standalone (nil = installed one)
    },

    experimental = {
      webtransport   = false, -- opt-in WebTransport/HTTP3 (falls back to WS)
      line_diff      = false, -- opt-in: send only changed lines per edit
      click_navigate = true,  -- default on: relative links open the file in nvim
      reverse_scroll = false, -- opt-in: scrolling the preview moves nvim's cursor
    },
  }
Example override:

  require("mdview").setup({
    server_port = 43219,
    browser = { browser = "firefox", browser_autostart = false },
    start   = { push_strategy = "try_push" },
    install = { repo = "your-fork/mdview.nvim", version = "v0.4.3" },
  })

Field reference

ft_pattern

  Filetype/glob patterns mdview's autocommands attach to. Globs, not bare
  extensions: *.markdown, not .markdown.

any_file

  Preview any normal text buffer, not just Markdown. Widens ft_pattern to
  { "*" } (overriding a hand-set one) and renders non-Markdown files as a
  syntax-highlighted read-only code view instead of through the Markdown
  renderer; scroll sync falls back to proportional, so there is no cursor
  line bar. Terminal, help, quickfix, scratch, binary and unnamed buffers
  stay excluded. Off by default. Was experimental.any_file before the
  2026-08-30 release check; the old key still works.

server_port / server_cwd

  Preferred port and optional working directory for the spawned
  mdview-server relay process. The relay itself falls back to the next free
  port if server_port is taken.

dev_server_port

  Vite dev server port; only relevant to the contributor dev workflow (see
  README.md's Development section), not to end users.

scroll_sync

  Send the cursor's line + total line count to the browser preview on
  CursorMoved/CursorMovedI, so it scrolls to follow (nvim-to-browser only;
  see |mdview-autocmds|). Set to false to disable.

scroll_sync_throttle_ms

  Minimum time between scroll-position pings sent to the relay.

sync_checkboxes

  When true (default), ticking a GFM task-list checkbox (- [ ] / - [x])
  in the preview writes the change back to the source: |:MDView-standalone|
  rewrites the file in the relay, |:MDView-start| edits the buffer (polled via
  the browser->Neovim bridge, since Neovim has no WebSocket client). Only the
  one marker character changes — indentation, bullet style and text are
  preserved. Set false to render checkboxes read-only and, in start mode,
  stop that poll.

sync_fields

  When true (default), editing a raw-HTML text field written in the source
  with a name (<input type="text" name="x"> or <textarea name="y">) and
  committing it (blur/Enter) writes its value back to the source. Raw HTML has
  no source position, so the field is located by its name attribute rather
  than by line — name must be unique per document, double-quoted. The value
  is HTML-escaped, so it can't break out of the tag. |:MDView-standalone|
  rewrites the file; |:MDView-start| edits the buffer. Set false to render
  such fields read-only.

edit_blocks

  When true, clicking a block in the preview (heading, paragraph, list item,
  code block, table, quote) replaces it with a text field holding the block's
  source lines; committing (blur / Ctrl+Enter, Enter in a one-line field)
  writes them back, Esc discards. |:MDView-start| replaces only that line
  range of the buffer, as one undo step; |:MDView-standalone| rewrites the file
  (the relay's --edit). An edit made against lines that changed since the
  preview was rendered is refused. Default false; |:MDView-edit| switches it
  for the running session.

shared_relay

  Opt-in (enabled = true): one relay process and one preview tab for every
  Neovim instance. The first |:MDView-start| spawns the relay detached and
  advertises it in stdpath("state")/mdview/relay.json; a |:MDView-start| in
  another instance attaches to it instead of spawning a second relay and tab.
  The tab follows the instance that gains the focus (FocusGained, needs a
  terminal with focus reporting; otherwise the first cursor move, buffer
  switch or insert in an instance), and only that instance pushes. Checkbox,
  field, block-edit, click-to-navigate and reverse-scroll write-backs go to
  the instance whose document the tab shows; with the same file open in two
  instances that is the focused one. |:MDView-stop| and quitting only detach;
  the relay ends, closing the tab, once no instance is attached any more
  (idle_timeout_s without a heartbeat counts as gone). Needs a relay with
  --shared (newer than v0.4.3; dev.binary_path). Details in
  docs/FEATURES/SHARED_RELAY.md.

open_preview_tab

  When true, |:MDView-start| opens an nvim-tab preview (see
  |:MDView-preview-tab|) instead of the browser. The relay/WASM pipeline still
  runs normally in the background, so |:MDView-open| can still open the
  browser afterwards if wanted.

browser.open_mode

  How the preview browser is opened:
    "default"  — open the URL in your normal default browser as a new tab
                 (your extensions/theme/profile apply). Uses the OS opener.
                 mdview cannot programmatically close it, so
                 browser_autoclose and stop_on_browser_exit are no-ops in
                 this mode. This is the default.
    "isolated" — spawn a dedicated browser process against a separate
                 mdview-only profile. Auto-close works (a distinct process),
                 but you don't get your extensions/bookmarks.
  All other browser.* fields except theme, open_url, browser_autostart
  and require_display apply to "isolated" mode only.

browser.theme

  Preview theme name, passed to the client as ?theme=. Ships: "github",
  "dark-dimmed" (darker, lower-contrast), "plain" (neutral), "tokyonight"
  (dark), and "catppuccin" (Latte/Mocha). Each follows the OS
  prefers-color-scheme where it defines both; append -light or -dark
  (e.g. "catppuccin-dark") to pin the color scheme. Switch at runtime with
  |:MDView-theme|. Add a theme by dropping a CSS file in src/client/themes/
  (import _base.css for the shared structure; optionally override --code-*
  for code colors) and a matching loader in main.ts.

browser.highlighter

  Code-fence syntax highlighter, applied client-side after each render and
  lazy-loaded so only the chosen one is fetched:
    "hljs"  — highlight.js (default). Light; token colors follow the theme's
              --code-* variables.
    "shiki" — exact TextMate/VSCode themes (tokyo-night, catppuccin, dark-plus,
              …) mapped from browser.theme; heavier, grammars load on demand.
    "nvim"  — Neovim's own colors. Nothing is tokenized in the browser: the
              highlighting color_my_ascii.nvim applied to the buffer is read
              back out through its public API, resolved to #rrggbb, and pushed
              per fenced block over the /spans channel. Preview and buffer then
              agree by construction — same colorscheme, same groups — and a
              :colorscheme change reaches the browser with the next push.
              A block color_my_ascii did NOT paint goes to highlight.js rather
              than losing its colors: its fence map covers 31 language tags,
              highlight.js knows about 190, so this is an addition to the
              JavaScript highlighter, not a replacement. color_my_ascii stays a
              soft dependency — without it there is simply nothing to send.
              The relay stores the last spans per room, so a reloaded tab is
              repainted at once instead of waiting for the next edit.
    "none"  — no highlighting.

browser.external_links

  Where links that leave the project open when clicked in the preview —
  http(s):, other URL schemes, and protocol-relative (//host/…) links:
    "new_tab"  — open in a new browser tab (default), so the preview tab is not
                 navigated away and stays live.
    "same_tab" — let the browser follow the link in place, replacing the
                 preview. Use Back to return.
  In-project relative links (and #anchors) are not affected here — those are
  handled by |mdview-experimental.click_navigate| when it is on.

browser.cursor_marker

  Show where the Neovim cursor is inside the preview:
    "line"  — a full-width band over the cursor's whole source line (default),
              covering every visual line when it wraps. Exact where the line's
              text is locatable (inline source spans, code blocks), otherwise
              the line's share of its sourcepos block. It marks the line, not
              the column. Color: CSS variable --cursorline-bg.
    "caret" — a caret at the exact cursor column. The WASM renderer wraps inline
              text/code runs in <span data-sp="…"> carrying their source
              position (byte columns, matching Neovim's byte-based cursor
              column); the client maps the cursor there with a DOM Range. Falls
              back to the line marker on blank lines and inside code blocks
              (whose content is re-tokenized by the highlighter). Documents
              render with the extra spans only in this mode.
    "block" — like "caret", but a box over the whole character under the
              cursor (its own width: a wide character or a tab gets a wide
              box; at the end of the line the box is one character wide), so
              it reads from a distance. Uses the same data-sp spans and the
              same line-marker fallback as "caret". Colors: CSS variables
              --cursor-block-bg and --cursor-block-border. Steady unless
              browser.cursor_blink is set (below).
    "section" — spotlight the whole heading section the cursor is in and dim
              the rest. The section runs from the governing heading (the last
              heading at/before the cursor) to just before the next heading of
              the same or higher rank, using the block data-sourcepos
              boundaries. A dimmed/lifted block survives video compression far
              better than a thin caret, so it's the clearest cue for a passive
              screen-sharing viewer.
    "off"   — no marker.
  All ride the scroll-sync ping, so they need |mdview-scroll_sync| on. Switch
  at runtime with |:MDView-cursor|.

browser.cursor_blink

  Blink the "block" cursor marker: false (steady, default), true (530 ms)
  or { ms = 530 } (period, clamped to 100..5000). Never blinks for a visitor
  whose system asks for reduced motion (prefers-reduced-motion). Passed to
  the preview as ?blink=<ms>; |:MDView-cursor| block applies it live.

browser.cursor_paragraph

  Tint the block the Neovim cursor is in, independent of the cursor marker: a
  paragraph (the text up to the next blank line), or a whole list, table, code
  block, block quote, heading or the frontmatter table -- each one block, also
  with blank lines inside. A cursor on a blank (or whitespace-only) line
  between blocks highlights nothing; the blank lines of a fenced code block
  left open at the end of the file are code and belong to it. Default:
  false (the line marker already shows the cursor; a block-sized tint
  moving with every keystroke is noise while editing) -- |:MDView-paragraph|
  toggles it.
                                                *hl-MdviewCursorParagraph*
  Color: the background of the highlight group MdviewCursorParagraph (links
  followed), read for every tab opened, with every |:MDView-paragraph| and,
  while the highlight is on, after every |:colorscheme| or 'background' change.
  Both updates reach every open tab, also with "new_tab"/"manual" and from an
  unnamed buffer (the tabs the relay reports connected, among the documents
  this Neovim pushed). Without one the preview theme's own faint tint is
  used. Rides the scroll-sync ping, so it needs |mdview-scroll_sync| on.
  |:colorscheme| runs ":highlight clear", which also empties a group defined
  once in the config; mdview then keeps the color the group had last, also
  for a tab opened later (a colorscheme defining the group itself replaces
  it). To set it per colorscheme, define it in a |ColorScheme| autocmd --
  mdview reads the group one tick after the event, so that autocmd always
  runs first:
    local function paragraph_hl()
      vim.api.nvim_set_hl(0, "MdviewCursorParagraph", { bg = "#2a3350" })
    end
    paragraph_hl()
    vim.api.nvim_create_autocmd("ColorScheme", { callback = paragraph_hl })
  Back to the theme's tint: clear the group and run |:MDView-paragraph| on
  (or a toggle that switches it on), which reads the group as it is, forgets
  the kept color and sends the tint to every open tab. Nothing else forgets
  it; off leaves it alone.

browser.selection_sync

  Mirror the Neovim visual selection into the preview: what you select with
  v, V or CTRL-V is highlighted in the browser, live, and disappears when
  you leave visual mode. Default: false — |:MDView-selection| toggles it.
  Meant for showing a document to other people — a lecture, a screen share, a
  walkthrough. Pointing at something in Neovim is invisible to an audience
  watching the browser tab; selecting it says "this part, here" in the window
  they are looking at. Off while you edit, for the same reason: an audience
  would otherwise watch you select things you are only operating on. Off costs
  nothing, so there is no third state to disable it in for good.
  All three visual modes keep their shape (charwise flows across lines,
  linewise covers whole lines, blockwise draws a column range on each line).
  The highlight is drawn as rectangles over the document, placed from the same
  data-sp source-position spans the "caret" cursor marker uses, so turning
  this on also renders documents with those spans. Fenced code blocks carry no
  spans and are located by their own line structure instead.
  Switch it off with |:MDView-selection|, which also clears a highlight that
  is currently drawn.

browser.spotlight_sync

  Mirror spotlight.nvim's whole-file highlights into the preview: a token you
  mark in Neovim is marked in every occurrence in the rendered document, in the
  same color, within about a second, and a re-render, removing a spotlight,
  clear, switching spotlight sets and a colorscheme change all update it.
  Default: true. A no-op without spotlight.nvim (it is looked up, never
  required), and independent of spotlight.nvim's own persistence: a spotlight
  that is not persisted is on screen, so it is mirrored. What leaves Neovim is
  the spotlight texts and colors, to the loopback relay and this session's
  tabs — set false, or use |:MDView-spotlight|, when a shared screen or a
  tab left open must not show what you marked.
  Only whole-file spotlights (toggle, add) are mirrored; "this occurrence
  only" ones are pinned to a buffer position the rendered document has no
  counterpart for. The text is matched literally and case-sensitively (unless
  the spotlight ignores case); a spotlight made from a visual selection matches
  any substring, one made from a word only between word boundaries. Needs a
  relay with the /spotlight route (v0.4.0+); install.version pins one that
  has it, an older pin needs dev.binary_path and dev.web_root pointed at a
  local build.

browser.spotlight_max_matches

  Most matches painted per spotlight in the preview (default 500), so a token
  that occurs thousands of times in a large document stays cheap to render. A
  spotlight that hit the limit is reported in |:MDView-weblogs|.

browser.display_lang

  Show the preview in another language than the buffer: a language code such as
  "en". Default: nil (off). The buffer is never touched; language.nvim
  (looked up with pcall(require), never required otherwise) translates the text
  line for line before it is sent, so the preview has exactly as many lines as
  the buffer and scroll sync, the cursor marker, click-to-navigate and the
  checkbox sync keep working. A first valid text goes out at once (translated
  where the cache has it), paragraphs are patched in as they finish, the
  finished document comes last; a failure keeps the original visible and is
  reported once. Nothing goes to a translation engine unless this is set (or
  |:MDView-lang| is used), and right before the first request the message names
  the engine (again when another one takes over).
  Text-field sync is off while it is on; not available in standalone mode.
  Switch at runtime with |:MDView-lang|.

browser.display_lang_trigger

  When a changed document is translated again: "idle" (default; after
  browser.display_lang_debounce_ms without typing), "save" (on |:write|)
  or "manual" (only on :MDView lang refresh). Never per keystroke. A buffer
  switch and the first push translate at once unless "manual".

browser.display_lang_debounce_ms

  Pause after the last edit before "idle" translates. Default: 800.

browser.display_lang_source

  Source language of the buffer; nil (default) lets the engine detect it.

browser.display_lang_engine

  Engine for the display language; nil (default) uses language.nvim's own
  configured one, with its fallback chain.

browser.transform

  A generic asynchronous hook between the buffer and the preview:
  function(lines, ctx, cb). Call cb with exactly as many lines as you got
  (another length is dropped and reported once); it may call back later, and
  the previous text stays visible meanwhile. ctx has path, bufnr,
  target, display_lang, reason and final. display_lang is the
  built-in user of the same pipeline and runs first.

browser.zoom

  Preview font-size zoom factor (1.0 = 100%, the default). |:MDView-start|
  sets #mdview-root's font-size to 16 * zoom px; the stylesheet sizes
  everything in em, so the whole document scales proportionally. Adjust at
  runtime with |:MDView-zoom| (applies live). A non-default value is carried on
  the browser URL (?zoom=) so a reopened tab starts at the same zoom.

browser.preserve_blank_lines

  Whether a run of two or more blank lines between blocks renders as that much
  vertical space (true) or collapses to a single paragraph gap (false, the
  default -- what CommonMark specifies). The spacing is added by the client as
  empty gap elements between the rendered blocks, not by rewriting the source,
  so |mdview-scroll_sync| and the cursor caret still map to the right lines.
  Blank lines inside a fenced code block are one block's content, not a gap
  between blocks, and are unaffected either way. Carried on the browser URL as
  ?blanklines=1; toggle at runtime with |:MDView-blanklines|.

browser.focus

  Whether the opened preview tab is allowed to take keyboard focus. "browser"
  (default) opens it in front as usual; "nvim" keeps focus in the editor so
  you can keep typing. "nvim" is clean on macOS (open -g), best-effort on
  Windows (captures the foreground window and restores it after opening — a
  window manager can still override it), and a no-op on Linux (there is no
  portable way to do it). Applies to the default open_mode only.

browser.behavior

  What happens to the preview when you switch to a different markdown buffer
  while a session is running:
    "reuse"   — the one open preview tab follows the active buffer (its
                content is pushed into that tab's room). Default.
    "new_tab" — each markdown buffer you switch to opens its own preview tab
                (once per file; respects browser_autostart).
    "manual"  — switching buffers does nothing; open other files explicitly
                with |:MDView-open|.
  |:MDView-pin| suspends the follow for as long as you want to keep one
  document on screen, without changing this setting.

browser.autodetect_browser

  Try to locate an installed browser automatically (chrome, chromium, edge,
  firefox, in that order) when browser / browser_cmd are unset.
  Isolated mode only.

browser.browser

  Friendly name of a browser to prefer, e.g. "chrome" or "firefox".

browser.browser_cmd

  Absolute path to a browser executable; takes precedence over
  browser / autodetection when set.

browser.browser_autoclose

  Whether |:MDView-stop| also closes the browser tab it opened.

browser.browser_autostart

  Whether |:MDView-start| opens a browser tab automatically.

browser.browser_args

  Extra CLI arguments passed to the resolved browser executable.

start.push_strategy

  "launcher" waits for the relay to become healthy, then performs one
  initial full push. "try_push" retries the initial push with exponential
  backoff instead of a single wait.

install.repo / install.version

  GitHub owner/repo and release tag the relay binary and client bundle are
  downloaded from. Override repo if you maintain a fork; override
  version to pin an older release.

standalone.binary_path

  Relay binary |:MDView-standalone| spawns. nil (default) uses whichever one
  install resolved. Standalone mode needs a relay built with --watch
  support (v0.3.0+), which the pinned release has; set this only to run a
  locally built one:

    require("mdview").setup({
      standalone = {
        binary_path = "~/repos/mdview.nvim/native/server/mdview-server",
      },
    })
  |:MDView-standalone| probes the binary first and reports a clear error if
  it's too old, rather than spawning a process that dies silently.

experimental.webtransport

  Opt in to the WebTransport (HTTP/3) client transport. The client
  feature-detects it and falls back to WebSocket on any failure, so this is
  always safe to enable — but there is no HTTP/3 relay backend yet, so today
  it always falls back. Future tech; see
  docs/Roadmap/WebTransportAPI/DESIGN.md.

experimental.line_diff

  Opt in to the line-diff transport: on each edit, send only the changed lines
  (as versioned \x03 envelopes) instead of the whole document, and have the
  client reassemble the full text. Saves bandwidth on large files; note that
  the client still re-renders the whole document (comrak needs full context),
  so on a loopback connection the benefit is modest. Correctness is preserved
  by versioning: a diff is applied only if its base matches the client's
  version, otherwise the client waits for the next full snapshot (sent on save
  and every 25 edits) and resyncs. The default full-text push remains the
  verified path.

experimental.click_navigate

  Click-to-navigate (on by default). Clicking a relative link in the preview
  (e.g. [other](sub/other.md)) is intercepted by the client and sent to the
  relay's /nav bridge; Neovim polls it while a session is active, resolves the
  href against the source document's directory, and opens the target with
  :edit. Opening it makes it the active buffer, so browser.behavior
  handles the preview switch. External links (http:, mailto:), in-page
  anchors (#…) and absolute paths are left to the browser. Set false to let
  the browser follow links itself. In-page anchors (a table of contents) jump
  to their heading in the preview regardless of this option.

experimental.reverse_scroll

  Opt in to reverse scroll (browser -> Neovim): scrolling the preview moves
  Neovim's cursor to the matching position — the complement of the always-on
  nvim -> browser scroll_sync. Implemented by polling the relay's
  /scrollback bridge, so it follows with a small lag rather than instantly
  (Neovim has no push channel back from the browser). Feedback loops are
  suppressed on both sides. Off by default. When on, the preview shows a small
  "⇅ scroll enabled" hint so a screen-sharing viewer knows they may scroll it.

5. COMMANDS *mdview-commands*

mdview.nvim registers one command, :MDView, built via lib.nvim's subcommand
composer (lib.nvim.bindings.usercmd.composer): every subcommand below completes on
<Tab>, including the typed arguments.                              *:MDView*

:MDView start [file] [cwd=...]                                *:MDView-start*
  Ensures the mdview-server relay binary and client bundle are installed
  (downloading them from GitHub Releases on first use, checksum-verified),
  spawns the relay process, attaches the buffer-change autocommands (see
  |mdview-autocmds|), and opens the browser preview. [file] and
  cwd=... are both optional and may appear in either order:
  [file] (tab-completed as a file path) targets that file instead of the
  current buffer (a relative path is relative to the current directory; the
  preview starts from the text of the buffer that has exactly that file
  open, unsaved changes included, else from the file on disk);
  cwd=... overrides server_cwd for this spawn only
  (port=N does the same for server_port). A cwd=/port= token whose
  value does not parse (port=808O, a bare cwd=) is rejected with a
  message rather than taken as the file to preview.
  Calling it again while already running is a no-op that still allows
  pushing a newly given [file] (cwd=... is ignored once running).

:MDView stop                                                    *:MDView-stop*
  Stops the relay process, detaches all mdview autocommands, shuts down the
  session, and — when browser.browser_autoclose is true (the default) —
  closes the browser tab |:MDView-start| opened.

:MDView toggle [file] [cwd=...]                                *:MDView-toggle*
  Starts the preview if no session is running, otherwise stops it. A thin
  dispatcher over |:MDView-start| / |:MDView-stop|; start-style args are
  forwarded when starting and ignored when stopping.

:MDView standalone [file] [--no-browser]                  *:MDView-standalone*
  Starts the preview with NO Neovim in the chain at all: the relay binary
  watches the file on disk itself and pushes changes straight to the browser.
  Cheapest and most robust option — but it previews the file as SAVED, so
  unsaved buffer changes don't appear until you |:write|, and there is no
  scroll sync or cursor marker (nothing tracks a cursor). Runs on
  server_port + 100 so it can sit alongside a normal session. With
  --no-browser the preview URL is reported in the notification, since a
  detached process's output goes nowhere.
  Requires a relay binary with --watch support (v0.3.0+); if the installed
  one is older, mdview says so instead of spawning a process that dies
  silently — see standalone.binary_path in |mdview-config|.
  See |mdview-standalone|.

:MDView open                                                    *:MDView-open*
  Re-opens a browser tab for the current buffer against the
  *already-running* session. It does NOT start a new relay process — run
  |:MDView-start| first. Pushes the current buffer's content once so the new
  tab isn't empty, then opens the browser using the same key/token URL logic
  |:MDView-start| uses. If no session is running, or the current buffer has
  no file path, it fails loudly via |vim.notify()| instead of doing nothing.

:MDView theme [name]                                            *:MDView-theme*
  Switches the preview theme at runtime. [name] is one of github,
  dark-dimmed, plain (optionally -light/-dark suffixed) and is
  tab-completed. Sets browser.theme in the live config and, if a session is
  running, re-opens the preview so the change applies now (a fresh tab in
  "default" |browser.open_mode|, since the old tab can't be closed
  programmatically). With no argument it reports the current theme.

:MDView weblogs                                               *:MDView-weblogs*
  Opens a scratch buffer showing the relay server's captured stdout/stderr
  log, including [client] lines the browser client POSTs back for
  diagnostics (connection status, render/theme errors). Subject to debug
  in |mdview-config|.

:MDView log [level]                                                *:MDView-log*
:MDView log export [path]                                   *:MDView-log-export*
  Shows mdview's own internal structured log ring (launcher, live-push,
  ws_client, …) in a scratch buffer — distinct from |:MDView-weblogs|,
  which shows the *relay's* stdout. [level] (trace/debug/info/warn/
  error, tab-completed) filters to that level and above; export [path]
  writes the ring to a file instead (default stdpath('log')/mdview-log.txt).

:MDView file-log                                              *:MDView-file-log*
:MDView file-log on [path]                                 *:MDView-file-log-on*
:MDView file-log off                                      *:MDView-file-log-off*
:MDView file-log status                                *:MDView-file-log-status*
:MDView file-log path [value]                            *:MDView-file-log-path*
  Toggles persistent file logging of the relay's stdout at runtime. It is
  opt-in and off by default, so a plain |:MDView-start| writes nothing to
  disk. When on, output is appended to file_log_path — by default
  stdpath('log')/mdview/relay-<timestamp>.log, never a logs/ directory
  in the current working directory. The bare form flips the state; status
  reports without changing it. See file_log in |mdview-config|.

  The destination can be set from the command line too:
      :MDView file-log on ~/mdview.log     enable and write there
      :MDView file-log path ~/mdview.log   set the path, leave on/off as-is
      :MDView file-log path                report the current path
      :MDView file-log path default        fall back to the configured default
  ~ and relative paths are expanded to an absolute path when the command
  runs, so a later |:cd| doesn't move the log file.

:MDView diagnose [path]                                      *:MDView-diagnose*
  Writes a full component-state diagnostics report to a file (default
  stdpath('log')/mdview-diagnostics.txt, or [path] if given) and opens
  it. Covers environment, dependencies, install cache, effective config, the
  running session with a live /health probe, the browser URL that would be
  opened, and the recent internal log ring — everything needed to hand a
  bug report off for debugging. If [path] cannot be written (missing
  parent directory, read-only location) an error is reported and nothing
  is opened.

:MDView preview-tab                                        *:MDView-preview-tab*
  Toggles an nvim-tab Markdown preview for the current buffer: a read-only
  mirror buffer in its own tab, highlighted via Neovim's markdown Treesitter
  parser (falls back to Vim's bundled syntax=markdown if the parser isn't
  installed). Live-synced on TextChanged/TextChangedI/BufWritePost.

  Deliberately decoupled from the browser/WASM rendering pipeline: no HTML
  is ever produced, no relay server or WebSocket is involved, and no
  external tool (e.g. glow) is shelled out to — this works standalone,
  with or without :MDView start ever having run. See |mdview-architecture|
  and open_preview_tab in |mdview-config| to make :MDView start open this
  instead of the browser.

Live preview controls

These change the open preview tab without a reload: each sets the matching
browser.* option (so a re-opened tab keeps it) and, while a session runs,
pushes a control update over the socket.

:MDView cursor [mode]                                        *:MDView-cursor*
  Sets the Neovim-cursor marker in the preview (browser.cursor_marker):
  line (blinking bar at the cursor line), caret (caret at the exact cursor
  column), block (a box over the character under the cursor; blinking via
  browser.cursor_blink), section (spotlight the current heading section,
  dim the rest), or off. No argument reports the current mode. Tab-completed.

:MDView edit [action]                                          *:MDView-edit*
  Switches block editing in the preview on/off (on|`off`|toggle; no
  argument toggles) — see edit_blocks above. Click a block to edit its
  source lines. Switching it off closes an editor that is open, without
  sending its content.

:MDView write [action]                                        *:MDView-write*
  Switches the cursor caret (|:MDView-cursor| caret) and block editing
  (|:MDView-edit|) together (on|`off`|toggle; no argument toggles).
  Without a running session, on/toggle starts one like |:MDView-start|,
  with both already on, so no second command is needed. off switches both
  off (a caret marker goes back to what it was before on; any other
  marker stays) and never
  stops the preview, so the same command switches writing on again. toggle
  is off when both are on, otherwise on: a mixed state (only one of the
  two on) turns both on. Optional keymap: keymaps.write (|mdview-keymaps|).

:MDView paragraph [action]                                *:MDView-paragraph*
  Switches the cursor paragraph highlight on/off (on|`off`|toggle; no
  argument toggles) -- see browser.cursor_paragraph above. In a running
  session the switch reaches every open tab (also with "new_tab"/"manual" and
  from an unnamed buffer); switching it on also sends the current color of
  |hl-MdviewCursorParagraph| and the cursor position, so the highlight appears
  at once. With no tab open yet the next one opened carries the setting.

:MDView selection [action]                                *:MDView-selection*
  Switches the visual-selection mirror on/off (on|`off`|toggle; no
  argument toggles) — see browser.selection_sync above. Off by default;
  this is the switch you flip when you start showing the document to someone.
  Switching it on prepares the tab at once (it re-renders with the source-
  position spans the mirror needs, so the first thing you point at appears
  without a hitch) and draws a selection that is already active. Switching it
  off clears a highlight that is drawn right now, instead of leaving it
  stranded in the tab.

:MDView spotlight [action]                                *:MDView-spotlight*
  Switches the spotlight.nvim mirror on/off (on|`off`|toggle; no argument
  toggles) — see browser.spotlight_sync above. On by default, and a no-op
  without spotlight.nvim. Switching it on sends the spotlights that are active
  right now; switching it off sends an empty state, so the highlights already
  shown in the open tabs disappear instead of staying behind.

:MDView sync [action]                                          *:MDView-sync*
  Pauses/resumes the nvim->browser scroll sync (pause|`resume`|toggle).
  While paused, moving the cursor no longer scrolls the preview or moves its
  cursor marker — useful to jump to a reference spot without dragging a
  screen-sharing viewer along. No argument reports the state.

:MDView pin [action]                                            *:MDView-pin*
  Holds the preview on the document it is showing instead of letting it follow
  the active buffer (on|`off`|toggle|status; no argument toggles).

  Under the default browser.behavior = "reuse" there is one preview tab and
  it follows you: switch Markdown buffers and the browser switches too. That
  is right while writing and wrong while reading -- opening a second file to
  check something takes the document you were showing off the screen, and only
  switching back brings it there again.

  While pinned, everything another buffer would send into the pinned tab's
  room is dropped at the source: the content push, the scroll ping, the
  visual-selection mirror, and (under "new_tab") auto-opened tabs. The pinned
  document's own edits, scrolling and selections still reach the preview
  normally -- a pin filters which buffer may drive the tab, it does not pause
  the session.

  off also catches the tab up with the buffer you are actually in, rather
  than leaving it on the released document until the next buffer switch.

  A pin is session state, not config: |:MDView-stop| and a fresh
  |:MDView-start| clear it, since it held that tab on that document.
  |:MDView-open| moves a live pin instead of being blocked by it -- it
  re-points the tab at the current buffer on purpose. Tab-completed.

:MDView zoom [step]                                            *:MDView-zoom*
  Adjusts the preview font-size zoom (browser.zoom). +/- step by 10%
  (clamped 50%-300%), reset returns to 100%, and a bare number sets a factor
  (1.5) or a percentage (150). No argument reports the current zoom. Handy
  when a video call downsamples the shared screen.

:MDView reveal [action]                                      *:MDView-reveal*
  Reveals/hides every *private block* at once (on|`off`|toggle). A fenced
  block with the info string private renders its contents as normal Markdown
  but is blurred by default, so third-party names/numbers stay hidden during a
  screen share. Reveal one block by clicking it, or all with this command.
  Live-only — a freshly opened tab always starts hidden.

:MDView lang [code]                                          *:MDView-lang*
  Shows the preview in another language than the buffer. <code> (en, fr,
  ... tab completed) switches it on, off restores the original at once,
  refresh translates the current document again now (what the trigger
  "manual" waits for); no argument reports the state: language, trigger,
  engine and progress. Sets browser.display_lang; a running session re-pushes
  the current buffer, otherwise the choice applies on the next |:MDView-start|.
  Needs language.nvim; not available in standalone mode. See
  browser.display_lang in |mdview-config|.

:MDView blanklines [action]                              *:MDView-blanklines*
  Switches whether the preview shows every blank line between blocks as extra
  vertical space, or collapses runs of them to a single paragraph gap --
  CommonMark's own behavior, and the default. on|`off`|toggle, tab
  completed; no argument toggles. Sets browser.preserve_blank_lines (so a
  reopened tab keeps it) and, while a session runs, pushes a live /control
  update so the open tab re-renders without a reload. See
  browser.preserve_blank_lines in |mdview-config|.

:MDView overlay [name] [action]                             *:MDView-overlay*
:MDView overlay list                                   *:MDView-overlay-list*
  Toggles a preview overlay (browser.overlays): an independent, toggleable
  layer drawn over the document. toc — a floating outline that highlights
  the section the cursor is in and shows how far along you are. keycast —
  the keys pressed in Neovim as a fading pill at the bottom, for lectures and
  recordings; off by default, needs ui.nvim (ui.screenkey.subscribe), and
  browser.keycast.scope decides what it shows: "normal" (default) only
  commands, no Insert, command-line, Select or terminal text;
  "insert_protected" Insert-mode and command-line text but never what is
  typed into a password prompt or a |:terminal|; "all" everything. A password
  a plugin reads with |getchar()| in a loop is shown in every scope. An
  overlay switched on
  without a session shows in the next tab. Without a name (or with list)
  it reports the known overlays and their state. Both arguments are
  tab-completed.

:MDView breadcrumbs                                     *:MDView-breadcrumbs*
:MDView breadcrumbs export [path]                *:MDView-breadcrumbs-export*
:MDView breadcrumbs clear                         *:MDView-breadcrumbs-clear*
  Shows/exports/clears the session breadcrumbs: a rough Markdown outline of
  which document + heading section the cursor was in and when, recorded while
  the session runs (deduped so a new line appears only on an actual section or
  document change). export writes a .md file (default
  stdpath('log')/mdview-breadcrumbs.md). Useful for writing notes and
  follow-ups after a call. Recording is gated by breadcrumbs
  (|mdview-config|, default true) and reset each session.

Lua API

                                                               *mdview.open()*
require("mdview").open({opts}) is the function behind |:MDView-open|.
{opts} (all optional): bufnr (default: the current buffer), browser_url
(explicit URL override), browser_cmd, browser_args, and for a generated
view render, name, on_click (see |mdview-generated|). Returns true on
success, false on failure (after notifying why).

                                                    *mdview-generated*
Generated view: another plugin's scratch buffer (any 'buftype', nofile
included) whose preview is Markdown the plugin renders:

  require("mdview").open({
    bufnr = buf,
    name = "caselog://case-1/app.log.md",  -- room + buffer name, must end in .md
    render = function(bufnr) return md_lines end,
    on_click = function(target, ctx) end,  -- optional, clicked relative link
  })
mdview asks render(bufnr) instead of reading the buffer, pushes again on
|TextChanged| and on |mdview.refresh()|, hands a clicked relative link
([x](entry/42) -> "entry/42") to on_click, leaves line-for-line features
(scroll/selection sync, write-back) alone and ends the view when the buffer is
deleted. Without a session, open starts one when the view is the current
buffer. Full contract: docs/generated-views.md in the repository.

                                                            *mdview.refresh()*
require("mdview").refresh([bufnr]) pushes a generated view again now (a
filter or folds changed, which the buffer text does not show). Throttled like
a text change. Returns false for a buffer that is no generated view, or
without a running session.

6. AUTOCOMMANDS *mdview-autocmds*

All registered in a single augroup (MdviewAutocmds) by
mdview.bindings.autocmds.attach() when |:MDView-start| runs, and torn down
together by |:MDView-stop|. The BufEnter handlers (snapshot, buffer switch,
breadcrumbs) share one autocmd, bindings/autocmds/enter_hub.lua.

Event Purpose

  BufEnter                        Take a session snapshot of the entered
                                   buffer.
  TextChanged, TextChangedI        Push the full current buffer content to
                                   the relay for live preview.
  BufWritePost                    Same full push, triggered on save.
  User SpotlightChanged,           Re-read spotlight.nvim's whole-file
  ColorScheme, OptionSet            spotlights and palette (debounced) and send
  background                        them to the relay when they changed, so
                                   the preview paints the same highlights;
                                   gated behind browser.spotlight_sync.
  CursorMoved, CursorMovedI         Send cursor line + total lines to the
                                   relay (throttled) so the browser preview
                                   scrolls to follow. nvim-to-browser only;
                                   gated behind scroll_sync (default true).
  VimLeavePre                     Stop the relay process so it doesn't
                                   outlive the Neovim session. NOT
                                   pattern-restricted to markdown files —
                                   this must fire regardless of which buffer
                                   is focused when Neovim quits, or the
                                   relay process is orphaned.

Two additional autocmd modules exist in the source tree but are intentionally
not wired up (on_text_change.lua, bufwrite.lua) — kept only for
reference; live_push.lua supersedes both.

7. KEYMAPS *mdview-keymaps*

mdview.nvim defines no keymaps by default — only the user commands in
|mdview-commands|. One action has an opt-in keymap in the config:

  keymaps.write = "<lhs>"   normal mode, |:MDView-write| toggle (cursor
                             caret + block editing together)

  require("mdview").setup({ keymaps = { write = "<leader>mw" } })
For anything else, map the commands yourself:

  vim.keymap.set("n", "<leader>mp", "<cmd>MDView start<cr>",
    { desc = "mdview: start preview" })
  vim.keymap.set("n", "<leader>mq", "<cmd>MDView stop<cr>",
    { desc = "mdview: stop preview" })
Since these are plain |vim.keymap.set()| calls with a desc, they show up
correctly in which-key.nvim (https://github.com/folke/which-key.nvim)
without any extra integration needed.

8. HEALTH CHECK *mdview-health*

                                                          *:checkhealth-mdview*
  :checkhealth mdview
Reports, without downloading or installing anything:

  - Neovim >= 0.9
  - lib.nvim present (a required dependency — reported as an error if missing)
  - curl found on PATH
  - tar found on PATH
  - Whether the mdview-server binary for the configured
    install.version is already cached, and where
  - Whether the client bundle for the configured install.version is
    already cached, and where

A missing binary/client bundle is reported as a warning, not an error — both
are downloaded automatically the first time |:MDView-start| runs.

9. ARCHITECTURE *mdview-architecture*

  plugin/mdview.lua                Load guard only (require('mdview').setup()
                                   does the actual work)
  lua/mdview/
    init.lua                       Public API: setup(), open()
    health.lua                     checkhealth provider
    config/
      init.lua                     Deep-merge setup() over DEFAULTS
      DEFAULTS.lua                 Single typed source of truth for defaults
      browser.lua                  Browser resolution config + validation
      usrcmd_start.lua             :MDView start strategy config
    core/
      state.lua                    Runtime handles (server proc, browser,
                                   session token)
      session.lua                  Per-buffer content snapshots
      events.lua                   Internal event helpers
    adapter/
      install.lua                  Downloads + checksum-verifies the relay
                                   binary and client bundle from GitHub
                                   Releases
      server_args.lua              Resolves the relay binary path + spawn args
                                   (port, token, web-root)
      runner.lua                   Cross-platform process spawn/stop
      ws_client.lua                Pushes buffer text to the relay over HTTP,
                                   with retry/backoff
      log.lua                      In-memory + optional file logging
      browser/                     Cross-platform browser executable
                                   resolution and launching
      preview_tab.lua               Standalone nvim-tab preview: no HTML, no
                                   relay/WebSocket, no external tool — a
                                   Treesitter-highlighted mirror buffer (see
                                   |:MDView-preview-tab|)
    bindings/
      usrcmds/                     :MDView <subcommand>, built via
                                   lib.nvim.bindings.usercmd.composer — one action
                                   module per subcommand (start, stop, open,
                                   toggle, theme, log, file_log, diagnose, …)
      autocmds/                    BufEnter, TextChanged*, BufWritePost,
                                   CursorMoved*, VimLeavePre wiring (see
                                   |mdview-autocmds|); preview_tab_sync.lua
                                   is separate, self-managing, and
                                   independent of :MDView start/stop
      keymaps.lua                  Opt-in keymaps from keymaps in setup();
                                   none by default (see |mdview-keymaps|)
    helper/                        Small cross-platform utilities; several
                                   delegate to lib.nvim

  native/server/                   Go relay server: binds 127.0.0.1 only,
                                   relays raw text over WebSocket per document
                                   key, serves the static client bundle
  native/wasm-render/               Rust crate compiled to WebAssembly:
                                   Markdown -> HTML (comrak) piped through an
                                   allowlist sanitizer (ammonia)
  src/client/                       Thin TypeScript glue: WebSocket transport
                                   + loads the WASM module + assigns its
                                   (already sanitized) output to the DOM

  docs/BINDINGS.md                  Cheatsheet of every command/autocmd
  docs/Roadmap/Roadmap.md           Planned features and fixed-bug log

Module load order: config -> core -> adapter -> bindings -> init

10. SECURITY MODEL *mdview-security*

mdview.nvim is designed so that no server-side process ever renders
Markdown, and no unsanitized HTML ever reaches the DOM:

  - Rendering AND sanitization happen together, client-side, inside the
    WASM module (comrak -> ammonia). There is no code path that returns
    rendered HTML without it having passed through the sanitizer first.
  - The Go relay only ever transports raw text. It has no rendering logic
    and therefore no HTML-related attack surface at all.
  - The relay binds to 127.0.0.1 only — never reachable from the network.
  - Every WebSocket upgrade is checked against the request's Origin header,
    rejecting cross-site/DNS-rebinding attempts against the local server.
  - Every request (WebSocket and HTTP) must present a per-session token,
    generated fresh each time |:MDView-start| runs and known only to the
    Neovim process and the browser tab it opens. In standalone mode
    (|:MDView-standalone|) the token is generated the same way, by whichever
    side started the relay; nothing about the check itself changes.
  - The downloaded relay binary and client bundle are checksum-verified
    against the release's published checksums.txt before first execution.

11. BACKGROUND & STANDALONE *mdview-standalone*

By default a preview lives and dies with your Neovim instance.
|:MDView-standalone| gives you one that stays, with no Neovim in the chain:

  Command              Survives :qa   Unsaved buffer   Scroll sync / cursor
  ------------------   ------------   --------------   --------------------
  |:MDView-start|          no             yes                 yes
  |:MDView-standalone|     yes            no (on disk)        no

Rule of thumb: |:MDView-start| while you're editing the document,
|:MDView-standalone| when you just want it rendered and kept open.

Typical uses

  - A reference doc (spec, API notes, cheat sheet) beside your work, running
    for days regardless of what you do to your editor.
  - Previewing a file that some other tool, or another person, generates.
  - The cheapest always-on preview: one small process, no Neovim, immune to
    whatever happens in your editor.

From the terminal

nvim +MDView --background file.md is NOT valid Neovim syntax — +cmd takes
no trailing flags. The supported spelling is the wrapper script:

  scripts/mdview-bg.sh README.md               # preview in the browser
  scripts/mdview-bg.sh --no-browser notes.md   # relay only, prints the URL
On Windows, scripts\mdview-bg.ps1 takes -NoBrowser. Each runs a throwaway
headless Neovim just long enough to fire |:MDView-standalone|, then quits; the
relay keeps running on its own. Symlink one onto your PATH for a
general-purpose "render this Markdown" command.

Environment: MDVIEW_PATH (mdview.nvim checkout; derived from the script by
default), LIB_NVIM_PATH (if lib.nvim isn't next to it),
MDVIEW_STANDALONE_BIN (relay override, same role as standalone.binary_path),
NVIM (binary).

Without a browser at all

|:MDView-preview-tab| renders the buffer as a read-only, Treesitter-
highlighted mirror in a Neovim tab — no relay, no WebSocket, no browser. Not
a full preview (no CSS, themes or rendered tables), but it needs nothing but
Neovim, which makes it the answer on a machine with no GUI.

Full guide with examples: docs/standalone.md in the repository.