Browser-based markdown preview for Neovim with live mermaid diagram rendering.
- Live preview — the browser updates within ~300ms of each edit, with scroll sync
- Mermaid and more — mermaid, KaTeX, Graphviz, WaveDrom, Nomnoml, ABC and Vega-Lite render out of the box, with inline syntax errors
- Zero dependencies — pure Lua, no Node.js or Deno; rendering happens in the browser via CDN (
curloptional for offline assets) - Syntax highlighting — fenced code blocks via highlight.js with configurable themes
- Colorscheme sync — mirror your Neovim colorscheme in the preview, live
- Multi-buffer — one preview per buffer;
:MdViewListjumps between them - Single page mode — all previews in one browser tab
- Table of contents — collapsible sidebar with active-heading tracking
- Terminal preview — render inside a Neovim split or tmux pane via the kitty graphics protocol
- Auto-cleanup — servers shut down when buffers close or Neovim exits
- Neovim >= 0.8
- A web browser
- Terminal preview only: kitty, Ghostty or WezTerm, plus a Chromium-based browser
{ "kcayme/md-view.nvim" }use("kcayme/md-view.nvim")setup() is optional since every option has a default. See docs/options.md for the full reference. Adding ---@type MdViewOptions enables LSP completion and hover docs:
---@type MdViewOptions
require("md-view").setup({
-- Port for the local preview server. 0 = auto-assign a free port.
port = 0,
-- Bind address. Must be a loopback address (127.0.0.1, ::1, localhost).
host = "127.0.0.1",
-- Browser executable. nil = auto-detect (open/xdg-open/cmd /c start).
browser = nil,
-- Milliseconds to debounce buffer updates before pushing to the browser.
debounce_ms = 300,
-- Custom CSS string injected into the preview page.
css = nil,
-- Auto-close the browser tab when the preview is stopped.
auto_close = true,
-- Show [md-view] notifications on open/stop.
verbose = true,
-- Open a new browser tab when entering a buffer that already has a preview.
follow_focus = false,
-- Scroll sync: "percentage" (proportional offset) or "cursor" (nearest source line).
scroll = {
method = "cursor", -- "percentage" | "cursor"
},
-- Color theme for the preview page.
theme = {
-- "auto" (follows 'background') | "dark" | "light" | "sync" (mirrors colorscheme live).
mode = "auto",
-- highlight.js theme for code blocks. nil = "vs2015" (dark) / "github" (light).
syntax = nil,
-- Highlight group overrides for CSS variable extraction (only used when mode = "sync").
highlights = {},
},
notations = {
-- Set enable = false on a notation to skip loading its library.
mermaid = {
enable = true,
theme = nil, -- nil = auto-chosen per theme
security_level = "strict", -- "strict" | "antiscript" | "loose" | "sandbox"
},
katex = { enable = true }, -- math fences and $...$ / $$...$$ inline math
graphviz = { enable = true }, -- dot / graphviz fences
wavedrom = { enable = true }, -- wavedrom fences
nomnoml = { enable = true }, -- nomnoml fences
abc = { enable = true }, -- abc music notation fences
vegalite = { enable = true }, -- vega-lite fences
},
-- Filetypes :MdView will preview. {} = any filetype.
filetypes = { "markdown" },
-- Auto-open (or re-focus) a preview when entering a qualifying buffer.
auto_open = {
enable = false,
-- Neovim events that trigger the auto-open check.
events = { "BufWinEnter" },
},
-- :MdViewList picker; works with any vim.ui.select replacement.
picker = {
-- Title/prompt shown at the top of the picker.
prompt = "Markdown Previews",
-- function(item) -> string; item = { bufnr, port, name }. nil = "name http://host:port".
format_item = nil,
-- Passed as opts.kind to vim.ui.select.
kind = nil,
},
-- Single-page mode: all previews share one browser tab (uses top-level `port`).
single_page = {
enable = false,
-- "filename" | "relative" | "parent" | function(ctx) -> string; ctx = { bufnr, filename, path }.
tab_label = "parent",
-- nil (inherit `auto_close`) | "page" (close window after last preview) | "tab" | false (= "tab").
close_by = nil,
},
-- Table of contents sidebar shown alongside the preview.
table_of_contents = {
enable = false,
position = "left", -- "left" | "right"
max_depth = 6, -- 1–6; headings deeper than this are omitted
},
-- Brief "Updated" pill shown in the preview after live changes land.
toast = {
enable = true,
debounce_ms = 500, -- quiet period before the pill appears
duration_ms = 3000, -- how long it stays visible
position = "top-right", -- "bottom-left" | "bottom-right" | "top-left" | "top-right"
},
preview = {
-- "browser" | "split" | "tmux" (split/tmux render in-terminal via kitty graphics).
target = "browser",
terminal = {
-- Chromium-based executable for headless rendering. nil = best-effort auto-detect
-- (PATH, Playwright/Puppeteer caches, macOS app bundles); set a full path if it isn't found.
browser = nil,
-- Device scale factor for the rendered page. "auto" = 2 on macOS (Retina), 1 elsewhere;
-- set 2 on a HiDPI Linux/Windows screen if the preview looks zoomed out.
scale = "auto",
-- Quiet time (ms) after the viewer is resized before it re-renders.
resize_debounce_ms = 200,
},
},
})| Command | Description |
|---|---|
:MdView [target] |
Open a preview for the current buffer. target is browser, split or tmux; any other value is used as the browser command (e.g. :MdView firefox). |
:MdViewStop |
Stop the preview |
:MdViewClose [all] |
Close preview panel(s) without stopping the server |
:MdViewRestart |
Restart all active preview servers |
:MdViewToggle |
Toggle the preview on/off |
:MdViewList |
Pick from all active previews |
:MdViewAutoOpen |
Toggle automatic preview on buffer enter |
:MdViewTheme [mode] |
Switch the live theme (dark, light, auto, sync); no argument cycles |
:MdViewZoom {in|out|reset|N} |
Zoom the terminal preview (+ / - / = in its viewer); lasts until Neovim exits. Browser previews use the browser's own zoom |
:MdViewFetchAssets |
Re-fetch vendor assets for offline use |
The plugin sets no keymaps. Bind the commands yourself:
vim.keymap.set("n", "<leader>mp", "<cmd>MdViewToggle<cr>", { desc = "Toggle markdown preview" })- Theming — syntax themes, custom CSS, colorscheme sync
- Notations — supported notations; enabling and configuring them
- Filetypes — restrict or expand which buffer filetypes open a preview
- Auto-open — open previews automatically on buffer enter; lazy.nvim setup
- Picker integration — dressing.nvim, Telescope, fzf-lua, snacks.nvim, mini.pick
- Single-page mode — multiplex all previews into one browser tab
| md-view.nvim | markdown-preview.nvim | peek.nvim | glow.nvim | render-markdown.nvim | markview.nvim | |
|---|---|---|---|---|---|---|
| Runtime dependency | None (curl optional) | Node.js + yarn | Deno | glow CLI (Go) | None | None |
| Renders where | Browser | Browser | Webview / Browser | Terminal float | Inline (extmarks) | Inline (extmarks) |
| Mermaid diagrams | Yes | Yes | Yes | No | No | No |
| Notation support | Mermaid, KaTeX, Graphviz, WaveDrom, Nomnoml, ABC, Vega-Lite | Mermaid | Mermaid | None | None | None |
| Live reload | Yes | Yes | Yes | No | Yes | Yes |
| Scroll sync | Yes | Yes | Yes | No | N/A | Yes (splitview) |
| Maintained | Yes | Yes | Yes | Archived | Yes | Yes |
