PlantUML - Code, Generate and Publish Mind-maps from GitPages

Introduction

This post mainly aims to provide an idea how we can use PlantUML to create mind maps and host them from GitPages without spending anything. It obviously need a computing device with browser and internet connection.

PlantUML

No need to have introduction again, as there were posts written earlier on the same. Just to summarize

• It is a textual representation of diagrams.
• Helps to version and compare changes applied.
• Can render in different visual formats from the same textual definitions.

Mind maps

It is diagramming model where information about one concept is represented in relation with other related topics. More on Wiki.

Coding Mind maps

The setup explained in previous post is enough for coding mind maps. PlantUML supports mind maps out of the box in latest versions as beta.

Rendering diagram

Though the ideal way to publish into web is HTML, there seems some issues in generating HTML files out of the box. So better get it into image formats and embed into HTML using <img> tag. 

If we are using our machines during development, it is easy to have control over the environment and install GraphViz and Java runtime needed for PlantUML. Now a days everybody uses continuous integration and delivery method. The CI/CD environments with full control mostly require fees and here we are trying to achieve without any cost. Let is see how to get the diagrams published in free?

One way is to use containers where entire ecosystem would be present and use it in CI/CD environment. Another way which we are going to see is via proxy service of PlantUML

Using the proxy service is very simple. The official www.plantuml.com site has a service hosted in below url

http://www.plantuml.com/plantuml/proxy?src=<accessible URL to the plantuml file>

This src query string pair accepts a source url where the PlantUML code file is present and returns converted image representation.

eg:The below URL gives the png file corresponds to the PlantUML file located at the path mentioned in src query string parameter
http://www.plantuml.com/plantuml/proxy?src=https://raw.githubusercontent.com/mind-maps/software/master/debugging/before-debugging-others-problem.puml

More details on controlling the behavior can be found in this post.

The moment we got the png back via an URL, we can easily publish using html files. No need to have CI/CD systems and dealing with containers or build environments.

Publishing

GitPages provides free sub domain based web site hosting free and we can host mind maps directly from the GitHub repository. Using the markdown, we can easily convert the above mentioned url into an link <a> or <img> tag.

eg:A link in markdown file (.md) can be denoted as below

[Debugging](http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/mind-maps/software/master/debugging/before-debugging-others-problem.puml)

Sample repo

Source repo which hosts the puml files & hosting .md files - https://github.com/mind-maps/software
Sub domain & URL based web site which GitPages gives for repo- https://mind-maps.github.io/software/

The .md files gets automatically converted into HTML and served. If there is index.md it would be taken as default when we didn't mention anything in the url. GitPages internally uses Jekyll and customization can be done. One such customization in the above repo is in below URL. Since Jekyll and customization is not in the scope of this post, please google for more details.

https://github.com/mind-maps/software/blob/master/_layouts/default.html

Below are not essential but just to give complete picture
Sub domain based organization URL - https://mind-maps.github.io/
Repo of organization web site - https://github.com/mind-maps/mind-maps.github.io

Enjoy documenting...