ASCImermaid.nvim

ASCImermaid.nvim renders Mermaid fenced code blocks inside Markdown buffers as terminal-native text diagrams. It is built for developers who live in Neovim, SSH sessions, TTYs, and headless machines where browser previews, desktop image viewers, and Electron apps are the wrong tool.

The plugin is intentionally a wrapper around an external Mermaid-to-text CLI. It owns Markdown detection, renderer invocation, Neovim virtual-line display, commands, health checks, and editing events. Mermaid parsing and layout fidelity belong to the CLI renderer.

Status

This repository is usable as an early Neovim plugin, but it is not a full Mermaid renderer.

Current support:

• Markdown buffers only.
• Mermaid fenced code blocks only.
• External renderer command receives Mermaid source on stdin.
• Virtual-line output above or below the source block.
• Renderer errors displayed inline.
• Manual demo renderer for local testing without installing a real CLI.

Known limits:

• Overlay placement is accepted by config but not fully implemented.
• No render cache yet.
• No source concealment yet.
• No standalone .mmd or .mermaid file support yet.
• The demo renderer handles only a small flowchart subset.

Requirements

• Neovim 0.10 or newer.
• A terminal that can display the chosen renderer output.
• A Mermaid-to-text CLI available on PATH.

By default the plugin calls:

mermaid-ascii

For local development, this repo includes:

scripts/asciimermaid-demo-renderer

The demo renderer is dependency-free and useful for checking plugin behavior. It is not meant to be the production renderer.

Installation

lazy.nvim

{
  "RokPre/mermaid.nvim",
  name = "mermaid.nvim",
  opts = {
    renderer = "mermaid-ascii",
    placement = "above",
  },
}

packer.nvim

use({
  "RokPre/mermaid.nvim",
  config = function()
    require("asciimermaid").setup({
      renderer = "mermaid-ascii",
      placement = "above",
    })
  end,
})

Native package path

Clone the repository into a Neovim package directory:

git clone https://github.com/RokPre/mermaid.nvim.git \
  ~/.local/share/nvim/site/pack/plugins/start/mermaid.nvim

Then start Neovim and run:

:checkhealth asciimermaid

Configuration

Defaults:

require("asciimermaid").setup({
  enabled = true,
  renderer = "mermaid-ascii",
  output_mode = "unicode",
  placement = "above",
  events = {
    "BufWinEnter",
    "BufReadPost",
    "BufEnter",
    "InsertLeave",
    "BufWritePost",
  },
  timeout_ms = 3000,
  max_width = "window",
})

Options:

• enabled: enable automatic rendering.
• renderer: executable name or path for the external CLI.
• output_mode: "unicode" or "ascii"; currently passed through config for renderer integration.
• placement: "above", "below", or "overlay"; overlay is not complete.
• events: autocmd events that trigger rendering. Passing this list replaces the defaults.
• timeout_ms: renderer job timeout.
• max_width: "window" or a positive integer used to clip virtual lines.

If you customize events, include BufWritePost if you want diagrams to update after :w.

Commands

• :ASCImermaidRender: render the current buffer.
• :ASCImermaidClear: clear rendered virtual lines in the current buffer.
• :ASCImermaidToggle: enable or disable rendering for the current buffer.
• :ASCImermaidInfo: print render state for the current buffer.

Usage

Open a Markdown file containing a Mermaid fenced code block:

```mermaid
flowchart TD
  A[Write notes] --> B[Render in terminal]
```

Render manually:

:ASCImermaidRender

The plugin also renders on configured events. By default that includes buffer entry, insert leave, and file write. In current manual testing, write-triggered updates are the reliable editing path; insert-leave behavior remains an area to stabilize across real Neovim sessions.

Local Demo

Run from the repository root:

nvim -n --cmd 'set rtp+=.' \
  --cmd "lua require('asciimermaid').setup({ renderer = vim.fn.getcwd() .. '/scripts/asciimermaid-demo-renderer', placement = 'above', max_width = 200 })" \
  test2.md \
  -c 'set filetype=markdown' \
  -c 'ASCImermaidRender'

You should see a text diagram above the Mermaid block. The manual test files test1.md through test6.md include expected demo output near the bottom of each file for visual comparison.

For broader release checks, use docs/manual-verification.md.

Health Check

:checkhealth asciimermaid

The health check reports:

• Neovim compatibility.
• Renderer executable availability.
• Current output mode and placement.
• Markdown parser availability information.

Testing

Run the in-repo test harness:

NVIM_LOG_FILE=/tmp/asciimermaid-nvim.log nvim --headless -n -u NONE \
  --cmd 'set shada=' \
  --cmd 'set rtp+=.' \
  -c 'luafile tests/run.lua' \
  -c qall

The harness is dependency-free and runs Lua specs under tests/.

Repository Layout

plugin/asciimermaid.lua          plugin entrypoint
lua/asciimermaid/config.lua      config defaults and validation
lua/asciimermaid/scanner.lua     Markdown fenced-block scanner
lua/asciimermaid/renderer.lua    async external CLI wrapper
lua/asciimermaid/display.lua     virtual-line display and highlights
lua/asciimermaid/controller.lua  event and render orchestration
lua/asciimermaid/commands.lua    user commands
lua/asciimermaid/health.lua      health checks
scripts/asciimermaid-demo-renderer
tests/
docs/manual-view.md

Publishing Checklist

Before advertising this as a stable plugin:

• Choose and document the production renderer CLI.
• Add a license file.
• Finish or explicitly hide incomplete overlay placement.
• Add render caching or changed-source guards.
• Stabilize insert-leave updates in real interactive sessions.
• Replace the demo renderer with the chosen production CLI path.