blackhat-7 / vellum.nvim

# vellum.nvim
A markdown preview for Neovim. It renders in a split beside your buffer, inside the terminal. GitHub-flavored markdown, with mermaid diagrams and display math as real images.
- **Live.** Every keystroke re-renders. Unchanged blocks come from a cache, so long documents stay fast.
- **Scroll sync, both ways.** The preview follows your cursor. Scrolling the preview scrolls the source.
- **Diagrams.** Mermaid renders in a headless Chrome and shows as an image, sized to your terminal font. Each one renders once and is cached on disk (capped at 100 MB).
- **Zoom.** Open any diagram or image full-screen, then zoom and pan with keys or the mouse.
- **Math.** Inline `$…$` becomes Unicode text; display math renders with KaTeX.
- **Styled.** Heading bands, code with syntax colors, tables, GitHub alerts, task lists, ` ` blocks, inline badges. Colors come from your colorscheme.
Colors follow your colorscheme, light or dark, diagrams included:
## Requirements
- Neovim ≥ 0.12 with `termguicolors`
- Node.js ≥ 20 (for mermaid diagrams and non-PNG images)
- For images: kitty or Ghostty. Works over ssh. In tmux, add:
 [code] 
- A Nerd Font for the alert and checkbox icons
## Install
With lazy.nvim:
 [code] 
lazy runs `build.lua` on install. It installs the diagram renderer: `npm ci` and a small headless Chrome download.
If diagrams don't show, run `:checkhealth vellum`. It checks Node, renders a test diagram, and says what your terminal or tmux setup is missing.
## Use
`:Vellum` toggles the preview. It also closes once no window shows the markdown file.
`:Vellum export` writes the markdown buffer to a PDF beside it. `:Vellum export notes.html` writes a self-contained HTML file instead. Exports are light, like GitHub, with diagrams, math, alerts and footnotes, and ` ` blocks opened.
In the preview:
- `gx` or ` ` on a link follows it. Web links open in your browser, `#heading` links jump to the heading, and links to other markdown files open them in the source window (the preview follows). Other files open in their default app.
- ` ` on a diagram or image opens it full-screen.
- `q` closes the preview.
Full-screen:
- `+` / `-` zoom. Ctrl+wheel zooms toward the mouse pointer.
- `hjkl`, the arrow keys or the mouse wheel pan.
- `0` fits the image to the screen.
- `q` or ` ` closes it.
To zoom without leaving the markdown buffer, map `require('vellum').zoom()`. It opens the image at your cursor:
 [code] 
Options (the defaults):
 [code] 
## Supported
| Markdown | Rendering |
|---|---|
| Headings | H1 band, H2 rule, colored levels |
| Emphasis, strike, `code`, links, bare URLs | styled inline |
| Lists, task lists, ordered lists | bullets per depth, checkboxes |
| Quotes and `> [!NOTE]` alerts | colored bar and title |
| Obsidian callouts (`> [!question]- Title`), `==highlight==`, `[[wikilinks]]` | callout colors and titles, marked text, links you can follow |
| Tables | aligned, wrapped to fit, zebra rows |
| Fenced code | tree-sitter syntax colors, language