puml-for-markdown

Clickable PlantUML diagrams in GitHub Markdown.

Point a Markdown comment at a .puml file. puml-for-markdown puts the rendered diagram next to it, and blocks in one diagram can open another.

Command-line tool and GitHub Action · Free and open source

npm i -g puml-for-markdown

Node.js 22 or newer · Linux, macOS and Windows · MIT license

A README with one diagram comment, then a click through the linked diagrams.
345GitHub stars 78forks 573npm downloads last week

Counts from November 19, 2026.

How it works

1. Write a diagram

Keep .puml or .plantuml files in your repo. !include, sprites and C4 diagrams work.

2. Point a comment at it

<!--![System view](./puml/system.puml)-->Leave out the ! to get a link instead of an image.

3. Run it

Run puml-for-markdown and the diagram appears next to the comment. Run it again after edits and it updates in place.

Try it

Click through a real example.

These are the example diagrams from the repo, exported by puml-for-markdown as linked SVG files. Click a yellow block to open the diagram it links to.

README.md<!--![System view](./puml/level_1_system_view.puml)-->
  1. System view
Open SVG
System view: videos go to two groups of labelers, whose labels go to model training and to the labeling system. The yellow Labeling System block links to the container view.

Exported with puml-for-markdown --local-images -f svg. The diagram content is placeholder text.

Quick start

Run it yourself, or let GitHub run it.

Command line
npm i -g puml-for-markdown
cd your-project
puml-for-markdown
  • Searches every folder and follows your .gitignore rules.
  • --check fails when the docs are stale, without writing anything.
  • --local-images -f svg exports SVG files and links to them.
  • --hot-reload reruns every 2 seconds while you edit.

All CLI options

GitHub Action
# .github/workflows/diagrams.yml
name: Diagrams
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  diagrams:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: danielyaa5/puml-for-markdown@v2
  • Regenerates diagrams on every push to main and commits only the files it changed.
  • Add mode: check on pull requests to fail when diagrams are out of date.
  • Runs on Linux, macOS and Windows runners.

Inputs and outputs

Who it's for

01 / Docs

Docs that live in GitHub.

GitHub draws Mermaid diagrams in Markdown, but not PlantUML. This fills that gap for READMEs and docs folders.

02 / Private repos

Private repositories.

No tokens and no image files to commit. Use your own PlantUML server when the diagrams themselves are private.

03 / Teams

Teams that review in pull requests.

The Action keeps diagrams current on every push, or fails pull requests whose diagrams are stale.

Good to know

  • Diagram links contain your diagram's source, encoded. The link shortener and the PlantUML server can read it. For private diagrams, use your own server with --puml-server-url and turn off shortening with -t.
  • Successful runs save .puml-cache.json so unchanged diagrams aren't rendered again. Add it to your .gitignore.
  • Comments inside code blocks and inline code are left alone, and links between diagrams that loop back fail with the chain shown.

Questions

Does GitHub render PlantUML in Markdown?

No. GitHub renders Mermaid diagrams in Markdown, but not PlantUML. puml-for-markdown adds the rendered image, or a link to it, next to a Markdown comment that names your .puml file.

Do I have to commit image files?

No. By default the Markdown links to the diagram on the PlantUML server, through a short link. If you want files in the repo, --local-images exports PNG or SVG files and links to those.

Does it work in private repositories?

Yes, without tokens. The links carry the diagram's source, so for private diagrams run your own PlantUML server with --puml-server-url and turn off shortening with -t.

How do I update a diagram?

Edit the .puml file and run the tool again, or let the GitHub Action do it. To change the link text or switch between image and link, edit the comment and rerun. There's no need to delete the old output.

What do I need to run it?

Node.js 22 or newer. Install it with npm i -g puml-for-markdown. Automated tests run on Linux, macOS and Windows.

Support

Found a bug or want a feature? Open an issue on GitHub.

By Daniel Yakobian · MIT license. puml-for-markdown is independent and is not affiliated with PlantUML or GitHub.