A feature-rich Neovim plugin for working with Mermaid diagrams β preview, format, lint, and render inline in your terminal.
| Feature | Description | Dependencies |
|---|---|---|
| Live Preview | Real-time browser preview via built-in Lua HTTP server + SSE | None |
| Dual Renderers | Standard mermaid.js or aesthetic beautiful-mermaid |
None |
| Floating Panel | In-editor control panel with URL, status, and quick actions | None |
| Inline Render | Render diagrams directly in Kitty/chafa-capable terminals | mmdc + chafa/Kitty |
| Auto-Format | Built-in Lua formatter for indentation and token spacing | None |
| Diagnostics | Lint with vim.diagnostic via mermaid-cli |
mmdc (optional) |
| Dark Mode | Auto-detects Neovim background setting, live-syncs preview |
None |
| Toolbar | Zoom, pan, copy PNG, download SVG in browser preview | None |
Using lazy.nvim:
return {
"kevalin/mermaid.nvim",
dependencies = { "nvim-treesitter/nvim-treesitter" },
config = function()
require("mermaid").setup()
-- Install the Tree-sitter parser:
-- :TSInstall mermaid
end,
}Note: Requires Tree-sitter for syntax highlighting. Install with
:TSInstall mermaid.
All options with defaults:
require("mermaid").setup({
format = {
shift_width = 4, -- Indentation size (spaces)
},
lint = {
enabled = true, -- Enable diagnostics via mmdc
command = "mmdc", -- Path to mermaid-cli executable
},
preview = {
port = 0, -- Server port (0 or nil for random available port)
renderer = "mermaid.js", -- "mermaid.js" or "beautiful-mermaid"
theme = "default", -- Theme name (renderer-specific)
},
})mermaid.js (official): Uses Mermaid's built-in themes β default, dark, forest, neutral.
beautiful-mermaid (aesthetic):
| Palette | Light | Dark |
|---|---|---|
| Zinc | zinc-light β
|
zinc-dark β
|
| Tokyo Night | tokyo-night-light |
tokyo-night-storm, tokyo-night |
| Catppuccin | catppuccin-latte |
catppuccin-mocha β
|
| Nord | nord-light |
nord |
| Dracula | β | dracula β
|
| GitHub | github-light |
github-dark |
| Solarized | solarized-light |
solarized-dark |
| One Dark | β | one-dark |
β = recommended starters
| Command | Description |
|---|---|
:MermaidPreview |
Open live browser preview (auto-updates on edit) |
:MermaidPreviewStop |
Stop the preview server |
:MermaidFormat |
Auto-format current buffer |
:MermaidRender |
Render inline in Kitty/chafa terminals |
:MermaidCopyURL |
Copy preview URL to clipboard |
vim.api.nvim_create_autocmd("FileType", {
pattern = "mermaid",
callback = function()
local buf = vim.api.nvim_get_current_buf()
vim.keymap.set("n", "<leader>mp", "<cmd>MermaidPreview<CR>",
{ buffer = buf, desc = "Mermaid Preview" })
vim.keymap.set("n", "<leader>mf", "<cmd>MermaidFormat<CR>",
{ buffer = buf, desc = "Mermaid Format" })
vim.keymap.set("n", "<leader>mr", "<cmd>MermaidRender<CR>",
{ buffer = buf, desc = "Mermaid Render" })
vim.keymap.set("n", "<leader>mc", "<cmd>MermaidCopyURL<CR>",
{ buffer = buf, desc = "Mermaid Copy URL" })
vim.keymap.set("n", "<leader>mx", "<cmd>MermaidPreviewStop<CR>",
{ buffer = buf, desc = "Mermaid Stop Preview" })
end,
})Input:
flowchart TD
A(Start) --> B{Is it sunny?}
B -- Yes --> C[Go to the park]
B -- No --> D[Stay indoors]
C --> E[Finish]
D --> E
Designed for modern, high-quality diagram rendering.
[!NOTE]
beautiful-mermaiduses a simplified parser. Complex diagrams with Font Awesome icons or edge labels (A --> |label| B) should usemermaid.js.
Supports the complete Mermaid feature set.
mermaid.nvim can render diagrams directly in your terminal. The available
path depends on both the terminal and Neovim version:
Kitty/Ghostty + Neovim 0.12+ βββ β
Kitty graphics protocol
Neovim 0.9.5β0.11 + chafa βββ β
ASCII/ANSI fallback
Browser preview βββ β
Universal fallback
Sixel / iTerm2 protocol βββ β³ Planned
Run :MermaidRender to try it. Kitty rendering is invoked without /dev/tty;
Neovim 0.12+ forwards the generated escape sequences through its host-TUI API.
Older Neovim versions remain supported and fall back to chafa when installed,
or can use :MermaidPreview in the browser.
| Extension | Filetype |
|---|---|
.mmd |
mermaid |
.mermaid |
mermaid |
Q: The preview opens but shows "Loading..." A: Make sure you have content in your buffer and the SSE connection is established. Check the connection status indicator (top-right of the preview page).
Q: :MermaidFormat broke my diagram
A: Add -- mermaid-format-ignore at the end of lines you want to skip. File a bug report with the Mermaid code if it's a genuine formatting error.
Q: How do I use mermaid-cli for diagnostics?
A: Install it globally: npm install -g @mermaid-js/mermaid-cli. The plugin auto-detects the mmdc binary.
Q: Can I use this without a browser?
A: Yes. Use :MermaidRender with Kitty or Ghostty on Neovim 0.12+, or install chafa for older Neovim versions.
Q: The preview page is white in dark mode
A: The plugin auto-detects your Neovim background setting. Run :set background=dark and the preview will sync. If it doesn't, restart the preview with :MermaidPreviewStop then :MermaidPreview.
Q: Does this work on Windows?
A: The plugin is Lua-based so it runs anywhere Neovim runs. The built-in server uses vim.loop which is cross-platform.
- Check the server:
:lua print(require("mermaid.server").port) - Manual open: Navigate to
http://localhost:<port>in your browser - Check logs:
:messagesfor Mermaid-related notifications
- Wrong indentation: Adjust
shift_widthin config - Broken syntax: Use
-- mermaid-format-ignoreon problem lines - Missing diagram type: Some block structures may need a custom pattern β open an issue
- Terminal detection:
:lua print(require("mermaid.render").detect_capability()) - Kitty/Ghostty: Neovim 0.12+ is required for graphics-protocol output; also check
kitty +kitten icat --help - Older Neovim: Install
chafa, or use:MermaidPreview - chafa:
chafa --versionshould print a version β₯ 0.8
- Ensure mmdc is installed:
which mmdc - Test manually:
echo "graph TD\nA-->B" | mmdc -i - -o /tmp/test.svg - Check config:
lint.enabledmust betruein setup
See CONTRIBUTING.md for:
- Project structure overview
- Development setup (
make test) - Code style guide
- Commit conventions (Conventional Commits)
- Live preview with SSE
- Built-in Lua HTTP server
- Dual renderers (mermaid.js + beautiful-mermaid)
- Auto-formatting
- Lint via diagnostics
- CI/CD (GitHub Actions)
- Dark mode adaptive preview
- Floating panel in-editor
- Terminal inline rendering
- Split-window preview mode
- SVG export with custom dimensions
- Snippet support for Mermaid diagrams
- Obsidian-style diagram embedding
- mermaid.js β Diagram rendering engine
- beautiful-mermaid β Aesthetic renderer
- svg-pan-zoom β Interactive zoom/pan
MIT β see LICENSE