obsidian-plantuml: PlantUML diagrams inside Obsidian

A diagram plugin for a note tool that has no PlantUML

obsidian-plantuml renders PlantUML diagrams in Obsidian, and it is the kind of small integration that fills a real gap.

Obsidian renders Markdown, and Markdown has no diagram language. Obsidian's own diagram support is Mermaid, which is fine for flowcharts and sequence diagrams and does not cover the rest of the UML vocabulary that PlantUML handles. So if your notes contain a state machine, an activity diagram, a class diagram or a component diagram, this plugin is how you get them drawn.

The plugin is MIT licensed and written in TypeScript, with the author named as Johannes Theiner. The releases are 1.8.0 in April 2024, 1.8.1 on 2026-04-30 and 1.9.0 on 2026-06-12, with the last push to the repository on 2026-10-17.

One detail in the repository is worth noticing, because it explains how Obsidian plugins are versioned. The package.json still carries the version 1.6.7, while the releases have reached 1.9.0. The files that matter for an Obsidian plugin are manifest.json and versions.json, and the version in the npm style package manifest is not the version Obsidian displays. The release tags are the real history.

The repository layout is the usual Obsidian plugin shape: a manifest.json, a src/ directory with the TypeScript source, an esbuild.config.mjs for the bundler, styles.css for the rendering styles, tests/ with vitest, a tsconfig.json, and eslint configuration in both the modern flat form and an older .eslintrc.js.

The topics are obsidian, obsidian-md, obsidian-plugin and plantuml, which is exactly the scope: one plugin, one diagram language, one note application.

Three rendering paths, and their trade-offs

The rendering path is a setting, and the README names three options.

The first is the PlantUML Online Server, the public one, which requires nothing on your machine beyond the plugin.

The second is a local .jar file. The PlantUML renderer is a Java program distributed as a jar, and pointing the plugin at a local copy means the diagram never leaves the machine. The cost is stated plainly: using the local rendering method is not as performant as using a server. The reason is not mysterious. A server keeps a PlantUML instance warm and answers a request for a diagram, whereas the local path has to start a Java process and render inside it, which is a JVM startup per diagram.

The third is hosting your own server, with the address specified in the settings. The README links the Docker image for the PlantUML server, the JEE distribution and PicoWeb, which is a lightweight server written in Go.

That third option is the one that resolves the tension between privacy and speed. A self-hosted server is fast, because it is warm, and it keeps the diagram source on infrastructure you control. The cost is one more container to run.

So the choice is between convenience, speed and where the diagram text is sent, and for a plugin that renders whatever is in your notes, that last question is the one worth answering first. A sequence diagram in a private repository, sent to a public rendering server, is diagram source leaving your machine every time the note is opened.

The code block languages, and what each produces

The usage section is short, and it works by choosing the language of the fenced code block.

Create a fenced codeblock using plantuml as the language, and specify your PlantUML code inside it. The example in the README is a chain of messages between five participants:

Bob -> Alice: hello
Alice -> Wonderland: hello
Wonderland -> next: hello
next -> Last: hello
Last -> next: hello
next -> Wonderland: hello
Wonderland -> Alice: hello
Alice -> Bob: hello

Two additional languages give you different output from the same source. To generate a diagram with higher resolution, use plantuml-svg, which produces an SVG rather than the default PNG. And you can use plantuml-ascii to generate ASCII art, which the README shows as the same sequence diagram drawn with box characters and arrows.

The ASCII output is worth a second look, because it is the option that lets a diagram survive in a note that is read in a plain text context, in a terminal, in a diff or in a text export. The price is stated in the known issues: ASCII can only ever generate sequence diagrams. So for a class diagram or a state machine the option is not merely lower fidelity, it does not work.

And the SVG option is not only about resolution. The known issues also say that some languages, like Chinese, are not rendered correctly, and that you should switch to SVG rendering. That is a font issue in the rendering path rather than in the plugin, and the plugin gives you the switch.

Linking a diagram to a note in the vault

The feature that makes this plugin more than a renderer is the vault link support, and the reason it needs a special syntax is a collision.

The syntax for weblinks in PlantUML is the same as for Wikilinks in Obsidian, so a special syntax is used, three opening brackets followed by the note name. The README points at the Obsidian documentation for the content of such a link.

That collision is the whole problem. Both systems want the same characters for different things: PlantUML wants [[link]] for a URL and Obsidian wants [[Note]] for a note in the vault. If the plugin passed the text straight through, every PlantUML diagram with a link would either break or produce a link to a URL that Obsidian then tried to resolve as a note.

So the triple bracket is an escape, and the price of the escape is that a diagram meant for PlantUML outside Obsidian needs its links rewritten. For a diagram that lives in a vault and is read by people who are in the vault, that is a fair trade. For a diagram you intend to paste into a document, it is a small incompatibility.

Normal web links are described in the PlantUML documentation, so the plugin passes those through unchanged and only intercepts the triple bracket form.

Including a .puml file, and why it needs local rendering

The plugin can also include a .puml file inside a diagram, and this works the same way as the official PlantUML preprocessing documentation describes.

The important condition is in the warning next to it: it only works when using local rendering.

The reason follows from how the two mechanisms work. The .puml inclusion is a preprocessing step, where the renderer reads a referenced file and splices its contents into the diagram before drawing. When the plugin renders through a server, it sends the diagram source as text over HTTP, and the server has no access to your vault's files, so it cannot resolve the include. When the plugin renders locally, the renderer runs on your machine, in your working directory, and can open the file itself.

That is a clean illustration of the boundary between the two rendering paths. Anything that needs the server to reach your files is impossible with a server, and anything that needs the server to be warm for speed is impossible with a local jar.

The practical consequence for a vault is that .puml includes, which are the natural way to share a sequence diagram across several notes, force the local rendering path, and the local rendering path is the slower one. For a vault with a lot of PlantUML, that is a real trade to make deliberately rather than discover.

Known issues, stated plainly

The README has a known issues section, and it is worth reading as a whole because the caveats are specific.

The first is a general statement: not all methods of using PlantUML support all different diagrams. Which methods support which diagram types is a property of PlantUML itself, and the plugin inherits it.

The second is that ASCII can only ever generate sequence diagrams. As noted earlier, that limits the plantuml-ascii option to one diagram type.

The third is that the PicoWeb server does not support clickable links in PNG diagrams. So if you run your own PicoWeb instance and want the links in a diagram to be clickable, the output format has to change, and the readme tells you so rather than leaving you to wonder why the links do nothing.

The fourth is that some languages, like Chinese, are not rendered correctly, and the advice is to switch to SVG rendering.

Taken together these four tell you something useful about the project. The limitations are inherited from PlantUML and from the rendering paths rather than being bugs in the plugin, and each one comes with the workaround. A plugin that documents its edges is a plugin you can plan around, and the fact that this one lists them in the README rather than only in an issue tracker is a sign of care.

The installation itself is the standard Obsidian route: Settings, then Community plugins, then Community Plugins, then Browse, and search for PlantUML.

The codebase and the tooling

The repository is small, and the package manifest tells you exactly how it is built and tested.

The dev script runs the esbuild config, and the build script runs the same config in production mode, so esbuild is the bundler and the two modes differ by a flag rather than by a separate pipeline. Linting runs eslint over the src directory, with the eslint-plugin-obsidianmd plugin, which knows the Obsidian API and catches the mistakes that come from using it wrongly. The tests run under vitest, with a watch variant, and jsdom is a development dependency because Obsidian's API touches the DOM.

The runtime dependencies are what you would expect for this job. plantuml-encoder is the piece that turns diagram source into the encoded form the server expects in the URL, and the matching type package is present. uuid is there for identifying configurations. localforage provides the browser storage abstraction Obsidian plugins use for persistence.

The CodeMirror packages are there for the editor side: commands, language, search, state and view. That is the Obsidian editor interface, and a plugin that wants to do anything with a code block, such as registering the plantuml language or adding a command, works through it.

The obsidian package itself is pinned at 1.13.1 as a development dependency, which is the API surface the plugin is compiled against.

For the alternative, the honest comparison is with the diagram support Obsidian already has. Obsidian renders Mermaid natively, with no plugin and no server, which covers flowcharts, sequence diagrams, class diagrams, state diagrams and a handful of others. PlantUML covers a wider slice of the UML vocabulary and has a large body of existing examples, but it needs a renderer, and the renderer is either a server or a local Java process. The difference in approach is that the native support costs nothing and renders the same set every time, while this plugin opens up diagram types Obsidian does not draw at the price of a renderer, a setting and, if you use the public server, a network call per diagram.

Editorial conclusion

obsidian-plantuml suits an Obsidian user whose notes contain sequence, class, state or activity diagrams and who wants the diagram to live in the same file as the text around it. It does not suit somebody who needs only the diagram types Obsidian renders natively, and it does not suit a vault whose diagrams are sensitive, since the hosted rendering path sends the diagram source to a third party server. Check three things before you install it: which rendering path you will use, because the local jar is not as fast as a server and including a .puml file only works locally, whether you want the ASCII output at all, since it can only ever produce sequence diagrams, and whether the language of your diagrams is one the renderer handles, because the README notes that languages like Chinese are not rendered correctly unless you switch to SVG. The last push to the repository was on 2026-10-17 and the newest release is 1.9.0.

Frequently asked questions

Official sources

1. Issues
2. joethei/obsidian-plantuml on GitHub
3. License: MIT
4. README
5. Releases