PlantUML in your IDE — VS Code, JetBrains, and Vim — three real workflows

Writing puml code isn’t the hard part — seeing the result while you write is. This post lays out the three real workflows for VS Code / JetBrains / Vim.

Pick an IDE based on scenario

• VS Code: front-end / TS / Python mainline; markdown + puml side-by-side
• JetBrains family (IDEA / PyCharm / GoLand): Java / JVM mainline; PlantUML is a built-in first-class citizen
• Vim / Neovim: sysadmin / embedded / keyboard-first; PlantUML fits because puml is text

VS Code: the jebbs.plantuml plugin

Install

Open the extension panel, search PlantUML, install PlantUML by jebbs.

Prereqs:

• Java (required — PlantUML is JVM-native)
• Graphviz dot (optional, only for complex diagrams)
• Or switch to PlantUML Server mode (skip local Java)

Configure preview

settings.json:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  // Use a local plantuml.jar to render (needs Java)
  "plantuml.render": "PlantUMLServer",
  "plantuml.server": "http://www.plantuml.com/plantuml", // default

  // Preview rendered next to the markdown
  "plantuml.previewRenderMethod": "PlantUMLServer",

  // Default export format
  "plantuml.exportFormat": "svg",

  // Word wrap behaviour for puml
  "editor.wordWrap": "on",
  "[plantuml]": {
    "editor.wordWrap": "off"
  }
}

Key features

• Side preview: Ctrl+Shift+D (Mac: Cmd+Shift+D) to open the PlantUML preview
• Export: Alt+Shift+E (Mac: Option+Shift+E) to export the current diagram as SVG/PNG/PDF
• Subgraph includes: !include works; configure search paths via plantuml.includepaths

1
2
3
4

"plantuml.includepaths": [
  "${workspaceFolder}/_diagrams",
  "${workspaceFolder}/docs/diagrams"
]

Gotchas

• CJK tofu in !include: add skinparam defaultFontName "Noto Sans CJK SC" at the top of puml
• Preview stuck / not refreshing: Java process deadlocked — restart VS Code or pkill plantuml
• plantuml.com slow from mainland: self-host a plantuml server (docker plantuml/plantuml-server) for a 5-10× speedup

LaTeX math formulas

The VS Code PlantUML plugin supports !include + jlatexmath, but you need to install the jlatexmath-minimal jar separately. Common syntax:

1

Bob -> Alice: $\\alpha + \\beta = \\gamma$

JetBrains IntelliJ: built-in PlantUML support

IDEA / PyCharm / WebStorm all officially support PlantUML out of the box — no extra plugin needed.

Key capabilities

• .puml file highlighting: write puml like regular code
• Live preview: Cmd+Shift+P opens the PlantUML Tool Window with a dual-pane editor — code on the left, render on the right
• Java integration: right-click → “Diagrams” → “Show Diagram” auto-generates a PlantUML class diagram from a Java class
• Export: right-click → “Save Diagram As…”

Speed up rendering

Help → Find Action → PlantUML, find “PlantUML server URL”. Change to a local server:

1

http://localhost:8080

Then run:

1

docker run -d -p 8080:8080 plantuml/plantuml-server

10× faster than default.

Project-level config

.idea/plantuml.xml:

1
2
3

<application>
  <component name="PlantUml" svg="true" prune="true" />
</application>

Or in ~/Library/Application Support/JetBrains/<version>/options/plantuml.xml.

Reverse-engineering UML classes

IDEA Ultimate can reverse class diagrams from Java code (Show Diagram), but only for the current module’s internals. If you want a manually maintained diagram, keep .puml files separate — IDEA can also import PlantUML diagrams into the UML class view (two-way).

Vim / Neovim: pure keyboard

Vim has no out-of-the-box PlantUML plugin; the community approach is gardenapple/plantuml-syntax + a custom preview command.

Required: syntax highlighting

1
2
3
4

" ~/.vimrc
Plug 'gardenapple/plantuml-syntax'

au BufRead,BufNewFile *.puml,*.iuml set filetype=plantuml

Live preview (asynchronous, stay in the editor)

1
2
3
4
5
6
7
8

" Render the current buffer via plantuml.jar to /tmp, then :!open
function! RenderPlantuml()
  let l:tmp = tempname() . '.svg'
  call system('plantuml -tsvg -o ' . shellescape(fnamemodify(l:tmp, ':h')) . ' ' . expand('%:p'))
  call system('open ' . shellescape(l:tmp))
endfunction

autocmd FileType plantuml nnoremap <leader>p :call RenderPlantuml()<CR>

Press <leader>p to render and open the SVG in the system viewer (Preview on macOS, xdg-open on Linux, start on Windows).

Telescope + live_preview

Neovim’s image.nvim can inline-display SVGs in supporting terminals (kitty / wezterm with the Sixel / iTerm protocol).

1
2
3
4
5
6
7
8
9
10
11
12
13

-- init.lua
require("image").setup({
  backend = "kitty",
  max_width = 80,
  max_height = 30,
})

vim.api.nvim_create_autocmd("FileType", {
  pattern = "plantuml",
  callback = function()
    -- your rendering pipeline
  end,
})

A nice workflow

1. vim foo.puml
2. <leader>p to render and open in browser
3. <leader>d to jump to the next participant
4. Close, return to vim

Comparing the three IDEs

One shared PlantUML workspace config

Apply to all IDEs. ~/.plantuml-config:

1
2
3
4
5
6

skinparam defaultFontName "Noto Sans CJK SC"
skinparam shadowing false
skinparam ArrowColor #5B7C99
skinparam ArrowThickness 1
skinparam nodesep 50
skinparam ranksep 50

Launch each IDE with -Dplantuml.config=~/.plantuml-config to load a global default skin.

Recap

• VS Code: jebbs PlantUML, local Java + self-hosted server is fastest
• JetBrains: built-in + switch to local server + Java reverse-engineered class diagrams
• Vim: syntax highlight + system('plantuml -tsvg') one-key render
• Common ground: defaultFontName for CJK, self-hosted server, never get blocked by plantuml.com cross-border

Next

• Data-driven PlantUML — generating diagrams from a database or API
• Embedding PlantUML in Hexo (server-side / client-side) (note: actual published slug is plantuml-render-from-hexo)