↓Zum Hauptinhalt springen
  1. Artikel/

PlantUML mit Hugo integrieren

IT Hugo Www Dokumentation
Inhaltsverzeichnis

PlantUML mit Hugo integrieren (lokaler Build, statische Auslieferung) #

Diese Anleitung beschreibt, wie PlantUML-Diagramme sauber in einen Hugo-basierten Webauftritt integriert werden – ohne Server, ohne externe Dienste, vollständig lokal und reproduzierbar.

Der Ansatz eignet sich besonders für:

  • technische Dokumentation
  • Netzwerk- und Infrastrukturdiagramme
  • Vereins- und Projektwebsites
  • transparente Darstellung komplexer Strukturen

Grundidee #

Diagramme werden zur Build-Zeit gerendert,
Hugo bindet ausschließlich fertige SVGs ein.

Vorteile:

  • kein Java / kein PlantUML auf dem Webhost
  • statische Dateien → schnell, sicher, wartungsarm
  • SVGs sind skalierbar, durchsuchbar und versionierbar

Voraussetzungen (lokal) #

  • Java Runtime (JRE reicht)
  • Graphviz (dot)
  • PlantUML
  • Hugo
  • make

Beispiel (Debian/Ubuntu):

sudo apt install default-jre graphviz make

PlantUML:

sudo mkdir -p /opt/plantuml
sudo cd /opt/plantuml
sudo wget https://github.com/plantuml/plantuml/releases/latest/download/plantuml.jar
alias plantuml='java -jar /opt/plantuml/plantuml.jar'

Projektstruktur (empfohlen) #

site/
├─ Makefile
├─ hugo.toml
├─ content/
│  └─ netzwerk/
│     └─ vlan.md
├─ diagrams/
│  ├─ vlan.puml
│  └─ system.puml
└─ static/
   └─ diagrams/
  • diagrams/ enthält nur .puml
  • static/diagrams/ enthält nur generierte SVGs
  • Hugo rendert keine PUML-Dateien

Makefile: PlantUML + Hugo #

PLANTUML = plantuml
PUML_SRC = $(wildcard diagrams/*.puml)
SVG_OUT  = $(PUML_SRC:diagrams/%.puml=static/diagrams/%.svg)

.PHONY: all diagrams hugo clean

all: diagrams hugo

diagrams: $(SVG_OUT)

static/diagrams/%.svg: diagrams/%.puml
	@mkdir -p static/diagrams
	$(PLANTUML) -tsvg $< -o ../static/diagrams

hugo:
	hugo --minify

clean:
	rm -f static/diagrams/*.svg

Ablauf:

  1. make diagrams → rendert SVGs
  2. make hugo → erzeugt Website
  3. make → alles in einem Schritt

Nutzung in Hugo-Markdown #

Beispiel: content/netzwerk/vlan.md

---
title: "VLAN-Struktur"
---

## Übersicht

![VLAN Übersicht](/diagrams/vlan.svg)

Die Grafik zeigt die logische Trennung der Netzsegmente.

SVGs werden von Hugo direkt ausgeliefert.

Optional: Hugo-Shortcode für Diagramme #

Shortcode anlegen #

layouts/shortcodes/plantuml.html

<figure class="plantuml">
  <img src="/diagrams/{{ .Get 0 }}.svg" alt="{{ .Get 0 }}">
  {{ with .Get 1 }}<figcaption>{{ . }}</figcaption>{{ end }}
</figure>

Nutzung im Markdown #


  vlan
  
  
VLAN- und Zonenstruktur

Vorteil:

  • konsistentes Layout
  • saubere Wiederverwendung
  • optional mit Bildunterschrift

Deployment (z. B. Shared Webhosting) #

Auf dem Webhost liegen nur statische Dateien:

public/
├─ index.html
├─ diagrams/
│  └─ vlan.svg
└─ ...

Upload z. B. per rsync oder SCP.

Keine Laufzeit-Abhängigkeiten, keine Prozesse, keine Angriffsfläche.

Best Practices #

  • Diagramme nicht manuell bearbeiten
  • .puml versionieren, SVGs generieren
  • Rendering immer lokal oder im CI
  • Webhost bleibt „dummer“ Fileserver

Fazit #

PlantUML und Hugo ergänzen sich hervorragend, wenn Rendering und Auslieferung strikt getrennt werden.

Build lokal – ausliefern statisch.
Einfach, transparent, robust.

↑