Extend Gitea with Mermaid
Something that has been on my to-do list for quite some time is the integration of Mermaid into my Gitea instance. For those who don’t know Mermaid: This is a markdown extension for fast drawing of UML charts and even Gantt charts. Why Mermaid? Because it runs completely client-side without additional services. The syntax is quite simple and powerful aswell. Once implemented,it looks like this:
No third parties
Unfortunately, the documented default is anything but privacy friendly. The Mermaid packages are supposed to be distributed via the third-party provider unpkg. I have excluded all 3rd parties with a CSP.
For this reason the files themselves have to be hosted. The most difficult part is to find the required ones. Unfortunately this is not obvious from the documentation. Also the Mermaid GitHub-Repo is not very supportive. So I’ve downloaded them manually from https://unpkg.com/browse/mermaid@8.5.1/dist/ and picked only the really needed ones:
- mermaid.min.js
- mermaid.min.js.map
Adjustment Reverse Proxy
Since I would like to keep my Gitea clean and since these files are static Javascripts, it makes sense to keep them in a subdirectory on the upstream reverse. This is done with the line
ProxyPass /myplugin/ !in the sites-available config file of the virtual web server in Apache. After an Apache restart, Mermaid is ready to use. Whether the directory is called /myplugin or something else is up to you. It should just not collide with the existing gitea paths.
Adjustment Gitea Footer template
Last but not least you have to customize the custom/footer.tmpl template in Gitea. Just add these lines there:
[code]{{{if .RequireHighlightJS}}
{{{end}[/code]
With your own domain and the directory you defined before. After this change also restart the Gitea service and you will enjoy the beautifully visualized UML charts, diagrams & Co.
One detail, however, is given to you when writing markdown documents. Of course I fell into this trap myself and wondered for an hour why Mermaid didn’t work for me. In the preview function of the editor only the Markdown is shown. Only after a document is saved, it can be sent to Mermaid.
Here is an example from the screenshot before. You will find more in the Mermaid documentation.
graph LR;
A[Box mit eckigen Kanten] -->|ein Link Text| B(Box mit runden Kanten)
B --> C{eine Entscheidung}
C -->|Eins| D[Ergebnis Eins]
C -->|Zwei| E[Ergebnis Zwei]Enjoy!