Why shouldn't I use the public PlantUML server URL?

Because the diagram source is encoded into the URL, which means your component names, service topology and database hostnames travel to a third-party server and sit in its logs. For an internal architecture diagram that is a disclosure most security teams would not sign off on.

How do I share a PlantUML diagram without hosting a server?

Render it locally with the jar or the CLI, then publish the resulting SVG inside an HTML page. The rendering stays on your machine or your CI runner, and the reader gets a URL.

SVG. PlantUML's SVG output keeps text selectable and stays sharp at any zoom, which matters for a class diagram somebody will be squinting at in a review.

Can I keep the .puml source next to the diagram?

Yes, and you should. Publishing the rendered diagram with its source underneath means the next change is a text edit reviewers can also read.

Does this work from CI?

Yes — render in the job, publish the page, and the build's architecture diagram has a stable URL instead of an artifact that expires.

Share a PlantUML diagram

You have architecture.puml in the repo, which is the right place for it: it diffs, it reviews, it lives next to the code it describes.

Getting it in front of someone is the problem. Three bad options present themselves, and the most convenient one is the worst.

The public server is a disclosure

plantuml.com/plantuml/svg/<encoded> is seductive — no setup, instant image. It also works by encoding your diagram source into the URL and sending it to a server you do not run.

For a tutorial example, fine. For the diagram naming your internal services, your queue topology and payments-db-prod.internal, you have just published your architecture to a third party's access log and to whatever crawls the link. Most security reviews would catch this; most people never think to run one on a diagram.

Render locally, publish the result

Rendering is a local operation. Keep it that way:

plantuml -tsvg architecture.puml     # → architecture.svg

Then wrap the SVG in a page and publish it. The source never leaves your machine, and the reader gets an ordinary URL:

<!doctype html>
<meta charset="utf-8" />
<title>Service architecture</title>
<main>
  <h1>Service architecture</h1>
  <!-- contents of architecture.svg, inlined -->
  <details>
    <summary>Source</summary>
    <pre><!-- architecture.puml --></pre>
  </details>
</main>

Inlining the SVG rather than linking it keeps the page self-contained — a linked architecture.svg is the same missing-sibling-file problem that makes a shared HTML report lose its CSS.

Keep the source under the diagram

The <details> block above is the habit worth forming. A reviewer who can see the .puml can tell you the arrow direction is wrong in the source's terms, which means the fix is a one-line diff rather than an interpretive exercise.

It also makes the diagram honest about being generated. Nobody wonders whether the picture and the file have drifted, because both are on the page.

From CI

If the diagram is generated in a build, publish it in the same job:

- run: plantuml -tsvg docs/architecture.puml
- run: ./scripts/publish-diagram.sh docs/architecture.svg

Updating the same report id on each run gives the architecture diagram one permanent address that always shows main — much better than a build artifact that expires in ninety days. The general pattern is in publishing from CI.

Worth knowing

-tsvg, not -tpng. Selectable text, no blur, smaller file.
!include resolves at render time. Shared stylesheets and sprite libraries need to be reachable when you run the jar, not when someone opens the page.
Comments anchor next to the diagram, so "this dependency points the wrong way" lands where the arrow is — see commenting on HTML.
5 MB per report body.

Try it

Free — unlimited reports, commenters and revisions.

Publish a diagram →