Hinweis: Dieser Artikel ist älter als 3 Jahre
Inhalte, Quelltexte oder Links können zwischenzeitlich überholt sein.

Die eigene gitea Instanz - Teil VI

Schon was länger auf meiner To-Do-Liste war die Integration von Mermaid in meiner Gitea-Instanz. Wer Mermaid nicht kennt: Das ist eine Markdown-Erweiterung zum schnellen Zeichnen von UML-Ablaufplänen, Diagrammen und sogar Gantt-Plänen. Warum ausgerechnet Mermaid? Weil es komplett im Client abläuft ohne zusätzliche Serverdienste und der Syntax einfach und zugleich mächtig ist. Einmal implementiert sieht das Ganze so aus:

Keine Drittanbieter

Leider ist der dokumentierte Standardweg alles andere als datenschutzfreundlich. Die Mermaid-Pakete sollen über den Drittanbieter unpkg zum Browser gelangen. Wie im letzten Teil beschrieben habe ich genau das mit einer CSP ausgeschlossen.

Aus diesem Grunde müssen die Dateien selbst gehostet werden, was aber kein Problem darstellt. Das schwierigste war fast schon herauszufinden, welche Dateien dafür benötigt werden. Leider wird das nicht direkt aus der ansonsten sehr guten Dokumentation ersichtlich. Auch im Mermaid GitHub-Repo sucht man sich einen Wolf, so daß ich mir händisch diese von https://unpkg.com/browse/mermaid@8.5.1/dist/ geladen und bei dieser Gelegenheit nach den wirklich benötigten Dateien aussortiert habe.

Benötigt werden nur:

• mermaid.min.js
• mermaid.min.js.map

Anpassung Reverse Proxy

Da ich gerne meine Gitea-Installation sauber halten möchte und es sich um diese Dateien um statische Javascripts handelt, bietet es sich an, diese in einem Unterverzeichnis auf dem vorgelagerten Reverse zu halten. Das erfolgt mit der Zeile

ProxyPass /myplugin/ !

in der sites-available Konfigdatei des virtuellen Webservers im Apachen. Die Reihenfolge ist wichtig, am besten über den anderen ProxyPass Einträgen setzen. Nach einem Apache Neustart ist Mermaid betriebsbereit. Ob das Verzeichnis /myplugin heisst oder irgendwie anders, das ist Euch überlassen. Es sollte nur nicht mit den bestehenden gitea Pfaden kollidieren.

Anpassung Gitea Footer-Template

Zuletzt ist noch das custom/footer.tmpl Template in Gitea anpassen. Dort einfach diese Zeilen hinterlegen:

{{if .RequireHighlightJS}}
<script src="https://domain.tld/myplugin/mermaid.min.js"></script>
<script>mermaid.init(".language-mermaid")</script>
{{end}}

Mit Eurer eigenen Domain und dem zuvor selbst definierten Verzeichnis. Nach dieser Änderung auch den Gitea Dienst einmal neu starten und Ihr kommt in den genuss von schön visualisierten UML Charts, Diagrammen & Co.

Ein Detail sei Euch aber beim Schreiben von Markdown Dokumenten auf den Weg gegeben. Natürlich bin ich selbst in diese Falle getappt und habe mich eine Stunde lang gewundern, warum Mermaid bei mir nicht funktioniert. In der Vorschau-Funktion des Editors wird einem nur das Markdown angezeigt. Erst nachdem ein Dokument gespeichert ist, kann dieses an Mermaid übermittelt werden.

Hier ein Beispiel zum Ausprobieren, das ergibt die oben im Screnshot sichtbaren Chart. Mehr Beispiele in der Mermaid-Dokumentation

graph LR;
    A[Box mit eckigen Kanten] -->|ein Link Text| B(Box mit runden Kanten)
    B --> C{fa:fa-shield eine Entscheidung}
    C -->|Eins| D[Ergebnis Eins]
    C -->|Zwei| E[Ergebnis Zwei]