✨ plantuml.nvim for Neovim ✨

A Neovim plugin for previewing and exporting PlantUML diagrams with browser preview, real-time ASCII preview, and high-DPI PNG export.

Introduction

This plugin provides seamless PlantUML integration for Neovim with the following features:

• Browser Preview: Generate SVG files and preview them in your default browser via a local server
• Real-time ASCII Preview: Preview PlantUML diagrams as ASCII art in a split Neovim window using the UTXT target
• High-DPI PNG Export: Export diagrams to high-resolution PNG files using Inkscape for crisp, publication-ready images
• Multiple Export Formats: Support for SVG, PNG, and UTXT (ASCII art) file generation
• Smart Window Management: Intelligent preview window creation and updates

Installation & Usage

Prerequisites

• Neovim >= 0.8.0
• Java (required if using plantuml.jar)
• PlantUML - either:
  • plantuml command available in PATH, or
  • plantuml.jar file (configure path in setup)
• Inkscape (optional, for high-DPI PNG export)
• Node.js

Filetype Configuration

Neovim does not recognize .puml and .uml file extensions by default. The lazy.nvim example below includes filetype detection via init function. Alternatively, you can add this to your init.lua (before lazy.nvim setup):

vim.filetype.add({
  extension = {
    puml = "plantuml",
    uml = "plantuml",
  },
})

Installation

Using lazy.nvim

return {
  "Mastttttter/plantuml.nvim",
  init = function()
    vim.filetype.add({
      extension = {
        puml = "plantuml",
        uml = "plantuml",
      },
    })
  end,
  ft = { "plantuml" },  -- Lazy load when opening .puml or .uml files
  config = function()
    require("plantuml").setup({
      java_cmd = "java",
      plantuml_jar = nil,        -- Path to plantuml.jar (optional if plantuml is in PATH)
      inkscape_cmd = "inkscape",
      server_port = 8912,
      png_dpi = 800,
    })
  end,
  keys = {
    { "<leader>vup", "<cmd>PlantumlPreview<cr>",     desc = "Preview PlantUML in browser" },
    { "<leader>vuu", "<cmd>PlantumlPreviewUTXT<cr>", desc = "Preview PlantUML as ASCII" },
    { "<leader>vus", "<cmd>PlantumlCreateSVG<cr>",   desc = "Create SVG file" },
    { "<leader>vug", "<cmd>PlantumlCreatePNG<cr>",   desc = "Create PNG file (high-DPI)" },
    { "<leader>vut", "<cmd>PlantumlCreateUTXT<cr>",  desc = "Create UTXT file" },
  },
}

Usage

1. Open a PlantUML file (.puml or .uml extension) in Neovim
2. Use the commands or keybindings below to preview or export your diagram

Commands & Keybindings

Command	Keybinding	Description
:PlantumlPreview	<leader>vup	Generate SVG and preview in default browser
:PlantumlPreviewUTXT	<leader>vuu	Generate UTXT and preview in a split window
:PlantumlCreateSVG	<leader>vus	Create SVG file in umlout/ directory
:PlantumlCreatePNG	<leader>vug	Create high-DPI PNG file (requires Inkscape)
:PlantumlCreateUTXT	<leader>vut	Create UTXT (ASCII art) file

Configuration

require('plantuml').setup({
  -- Path to java command (default: "java")
  java_cmd = "java",
  
  -- Path to plantuml.jar file (optional, uses system plantuml if not set)
  plantuml_jar = nil,
  
  -- Path to inkscape command (default: "inkscape")
  inkscape_cmd = "inkscape",
  
  -- Server port for browser preview (default: 8912)
  server_port = 8912,
  
  -- DPI for PNG export via Inkscape (default: 800)
  png_dpi = 800,
})

Configuration Options

Option	Type	Default	Description
java_cmd	string	"java"	Path to Java executable (used with plantuml_jar)
plantuml_jar	string | nil	nil	Path to plantuml.jar file. If nil, uses system plantuml command
inkscape_cmd	string	"inkscape"	Path to Inkscape executable for PNG conversion
server_port	number	8912	Port for local preview server
png_dpi	number	800	DPI resolution for PNG export

Notes

• Temporary Files: All temporary files are stored in /tmp/plantuml.nvim/

• Browser Preview: SVG preview runs a local HTTP server to serve the generated files

• Output Files: The PlantumlCreate* commands save files to <project-folder>/umlout/:

  • The plugin detects the project folder by finding the first parent directory containing .git
  • If no .git is found, the buffer's current working directory is used

• Smart Window Management: PlantumlPreviewUTXT intelligently manages the preview window:

  • Creates a new split window if no preview window exists
  • Updates the existing buffer if a preview window is already open

• Inkscape Command: PNG generation uses Inkscape with the following command pattern:

  inkscape --export-dpi=800 --export-filename=output.png input.svg

License

MIT License

An incredible fact

This project is my first try using OpenCode, even most of this README.md. The only part purely finished by myself is README_FOR_AGENT.md.