Create a post announcing and explaining Kroki usage

_posts/2021/05/2021-05-21-diagrams-from-textual-descriptions.md

+---
+title: "GitLab - Create Diagrams From Textual Descriptions"
+title_image: clark-tibbs-oqStl2L5oxI-unsplash.jpg
+data: 2021-05-21
+authors:
+  - huste
+layout: blogpost
+categories:
+  - tutorials
+excerpt: >
+    Recently, the Helmholtz-wide software development platform has been extended
+    with the ability to create diagrams from textual descriptions.
+    This post will help you getting started with this new feature.
+
+---
+
+{{ page.excerpt }}
+
+## Quick-Start Example
+Let us jump right in with an example by creating a UML sequence diagram.
+Any of these examples can be used in a place on <https://gitlab.hzdr.de>
+where Markdown is supported:
+  * Comments
+  * Issues
+  * Merge requests
+  * Milestones
+  * Snippets (the snippet must be named with a `.md` extension)
+  * Wiki pages
+  * Markdown documents inside repositories
+
+Therefore, put this content describing the diagram in any of the items
+listed above.
+
+    ```plantuml
+    @startuml
+    participant User
+
+    User -> A: DoWork
+    activate A
+
+    A -> B: << createRequest >>
+    activate B
+
+    B -> C: DoWork
+    activate C
+    C --> B: WorkDone
+    destroy C
+
+    B --> A: RequestCreated
+    deactivate B
+
+    A -> User: Done
+    deactivate A
+    @enduml
+    ```
+
+This description is then converted into this sequence diagram.
+
+![PlantUML sequence diagram](https://kroki.hzdr.de/plantuml/svg/eNpljkEKwzAMBO_7Cn0gHwjBYDsvKJSejaODKcSpohb6-1pOIYVedNDuzu6WREsuW1qVrjsLYJcGR36kud6q3JGylldSJg94k8JI00RZuD0v_HjyruTc6QtAMF_8R0REGg6ECXNdGUvLS303zWJH9Rcbe8fSLL_wPsJ2Gr8DzokfZu9AWw==)
+
+## How Does That Work?
+In the background a tool called [Kroki](https://kroki.io) is doing the magic.
+It takes the textual description and converts it into an image.
+The example shown above is using [PlantUML](https://plantuml.com/) to create
+the diagram of our choice (see line 1).
+
+So all you need to do is to create the textual description of your diagram and
+put it into GitLab Markdown.
+When viewing the content, in the background we will make sure that you are
+presented an image of your diagram description.
+
+## Step-By-Step Guide
+In this example our goal is to create a visual representation of JSON data.
+Let's take this example JSON data.
+
+<details>
+  <summary>Show JSON data</summary>
+  <div markdown=1>
+```json
+{
+  "firstName": "John",
+  "lastName": "Smith",
+  "age": 28,
+  "address": {
+    "streetAddress": "Bautzner Landstr. 400",
+    "city": "Dresden",
+    "state": "Saxony",
+    "postalCode": "01328"
+  },
+  "offices": [
+    {
+      "building": 512,
+      "room": 1234
+    },
+    {
+      "building": 312,
+      "room": 3
+    }
+  ],
+  "departments": []
+}
+```
+  </div>
+</details>
+
+We will use PlantUML to [display the JSON data](https://plantuml.com/json).
+
+At first, we need to tell GitLab that we want to create a diagram using
+PlantUML.
+This is why we create a Markdown code block using PlantUML for Syntax Highlighting.
+
+    ```plantuml
+
+    ```
+
+The [PlantUML documentation](https://plantuml.com/json) tells us how such a
+visual representation can be created.
+In this case you need to embed the JSON data into a block starting with
+`@startjson` and ending with `@endjson`.
+
+    ```plantuml
+    @startjson
+    {
+      "firstName": "John",
+      "lastName": "Smith",
+      "age": 28,
+      "address": {
+        "streetAddress": "Bautzner Landstr. 400",
+        "city": "Dresden",
+        "state": "Saxony",
+        "postalCode": "01328"
+      },
+      "offices": [
+        {
+          "building": 512,
+          "room": 1234
+        },
+        {
+          "building": 312,
+          "room": 3
+        }
+      ],
+      "departments": []
+    }
+    @endjson
+    ```
+
+You will be presented an image as shown below.
+
+![PlantUML JSON example](https://kroki.hzdr.de/plantuml/svg/eNp1kDurAjEQhfv9FSH1IvtQECvv1UrExlIsopnVXHYnkozgg_3vThJWC7lNIN85M-cwc0_K0Z-3mD0zIWRjnKeN6kDOhFzZM8o84FZ96LYzdE5YnQKppumjtQPvGYRNDDw5APp5Y_mrrvRAcGKtULM6EuOiiJvYfTR0D6YluzXggLkfpVh1s3gf8MWy0C6sjlpR1tVUstLHJrZpzBFC5C66Ux8WDlfTaoMnViZllQ_YWdsxKqt6HFGf_ztWf4_VaYbffUzXcOGTdoAUG-yzPpsD6nDjF8HSYBU=)
+
+## What Else Can Be Done?
+The new feature is not limited to using PlantUML.
+The new integration gives you access to more than that.
+It supports [Vega](https://github.com/vega/vega),
+[C4 with PlantUML](https://github.com/RicardoNiepel/C4-PlantUML),
+[GraphViz](https://www.graphviz.org/) or
+[BlockDiag](https://github.com/blockdiag/blockdiag).
+For a complete list please refer to the official
+[list of supported diagram types and formats](https://kroki.io/#support).
+
+### Vega
+
+<details>
+  <summary>Show code</summary>
+  <div markdown="1">  
+    ```vega
+    {
+      "$schema": "https://vega.github.io/schema/vega/v5.json",
+      "description": "A nested bar chart example, with bars grouped by category.",
+      "width": 300,
+      "padding": 5,
+      "autosize": "pad",
+    
+      "signals": [
+        {
+          "name": "rangeStep", "value": 20,
+          "bind": {"input": "range", "min": 5, "max": 50, "step": 1}
+        },
+        {
+          "name": "innerPadding", "value": 0.1,
+          "bind": {"input": "range", "min": 0, "max": 0.7, "step": 0.01}
+        },
+        {
+          "name": "outerPadding", "value": 0.2,
+          "bind": {"input": "range", "min": 0, "max": 0.4, "step": 0.01}
+        },
+        {
+          "name": "height",
+          "update": "trellisExtent[1]"
+        }
+      ],
+    
+      "data": [
+        {
+          "name": "tuples",
+          "values": [
+            {"a": 0, "b": "a", "c": 6.3},
+            {"a": 0, "b": "a", "c": 4.2},
+            {"a": 0, "b": "b", "c": 6.8},
+            {"a": 0, "b": "c", "c": 5.1},
+            {"a": 1, "b": "b", "c": 4.4},
+            {"a": 2, "b": "b", "c": 3.5},
+            {"a": 2, "b": "c", "c": 6.2}
+          ],
+          "transform": [
+            {
+              "type": "aggregate",
+              "groupby": ["a", "b"],
+              "fields": ["c"],
+              "ops": ["average"],
+              "as": ["c"]
+            }
+          ]
+        },
+        {
+          "name": "trellis",
+          "source": "tuples",
+          "transform": [
+            {
+              "type": "aggregate",
+              "groupby": ["a"]
+            },
+            {
+              "type": "formula", "as": "span",
+              "expr": "rangeStep * bandspace(datum.count, innerPadding, outerPadding)"
+            },
+            {
+              "type": "stack",
+              "field": "span"
+            },
+            {
+              "type": "extent",
+              "field": "y1",
+              "signal": "trellisExtent"
+            }
+          ]
+        }
+      ],
+    
+      "scales": [
+        {
+          "name": "xscale",
+          "domain": {"data": "tuples", "field": "c"},
+          "nice": true,
+          "zero": true,
+          "round": true,
+          "range": "width"
+        },
+        {
+          "name": "color",
+          "type": "ordinal",
+          "range": "category",
+          "domain": {"data": "trellis", "field": "a"}
+        }
+      ],
+    
+      "axes": [
+        { "orient": "bottom", "scale": "xscale", "domain": true }
+      ],
+    
+      "marks": [
+        {
+          "type": "group",
+    
+          "from": {
+            "data": "trellis",
+            "facet": {
+              "name": "faceted_tuples",
+              "data": "tuples",
+              "groupby": "a"
+            }
+          },
+    
+          "encode": {
+            "enter": {
+              "x": {"value": 0},
+              "width": {"signal": "width"}
+            },
+            "update": {
+              "y": {"field": "y0"},
+              "y2": {"field": "y1"}
+            }
+          },
+    
+          "scales": [
+            {
+              "name": "yscale",
+              "type": "band",
+              "paddingInner": {"signal": "innerPadding"},
+              "paddingOuter": {"signal": "outerPadding"},
+              "round": true,
+              "domain": {"data": "faceted_tuples", "field": "b"},
+              "range": {"step": {"signal": "rangeStep"}}
+            }
+          ],
+    
+          "axes": [
+            { "orient": "left", "scale": "yscale",
+              "ticks": false, "domain": false, "labelPadding": 4 }
+          ],
+    
+          "marks": [
+            {
+              "type": "rect",
+              "from": {"data": "faceted_tuples"},
+              "encode": {
+                "enter": {
+                  "x": {"value": 0},
+                  "x2": {"scale": "xscale", "field": "c"},
+                  "fill": {"scale": "color", "field": "a"},
+                  "strokeWidth": {"value": 2}
+                },
+                "update": {
+                  "y": {"scale": "yscale", "field": "b"},
+                  "height": {"scale": "yscale", "band": 1},
+                  "stroke": {"value": null},
+                  "zindex": {"value": 0}
+                },
+                "hover": {
+                  "stroke": {"value": "firebrick"},
+                  "zindex": {"value": 1}
+                }
+              }
+            }
+          ]
+        }
+      ]
+    }
+    ```
+  </div>
+</details>
+
+![Sample Vega diagram](https://kroki.hzdr.de/vega/svg/eNqtVzuP2zgQ7vdXCMQVl0DQyl5vEmx3xRVXXYArUgRGQEm0zFuJFEjKsdfQf8-QepEi5d0EaQxp-M17vhF9vYsi9IfMj6TG6ClCR6Ua-XR_fyIlTkqqjm2WUH7fA4z0_vSY_C85Q7FWLYjMBW0UBQGo_xUxIhUpogyLKD9ioSJyxnVTkTj6Dta0XEal4G2jQZcox4qUXFyS3tx3WqgjGHpIU_Pe4KKgrATJo3nHreKSvhDtC85ASUslLRmuJAi_wmsUXc0vHDBcG6jArCT_KdKgOEInXLVaujUuDC6jrADJFVHWtGrS0OiaMuMdnvBZP6XwKLWpp2jTGQNdHPZKGSPi85CB5ThNNm_3nE6e0-Tj7DpN0le881ateN_-mvfdz3g_EloeFZo8tU0BndYnSpCqovLvsyJMfd3sUW8Hfvd9NwGI11upWhgmORs2ac2tNzoID6FnWgPrdHJ4-pA8dPGrqF2yXUdls61P66h8RD0mGw-18Wztkp2H2nqoh-RxHZXPcW27AbSfaqSgq_LARe2WaXrSkEtjyovLUgDJoVWxfWwYm120fl-pDO0dwIGSqjBtgDDcI970cnwiAsNwuad4UpqkUwI3J2yYo3kSJG9FHpyR352_FWp825x22lamYiZRJBvMXNPk3AhnR0XvYUuyApA5-RPI0NZJzlum4sheKHFkE_wdenNIUuH8GfnNm6J7syViKLxi6rJxD_od7S0AtNb1eR_IHFfkxnI_G8Dc7YLX2Cyv67hKpoGw4svRlB5i1MyNEi2ZZC9E8KUMhsDsS1doNubT-O26ObM5r7iw5nIoJBfQQyiOb3P8PN7ObmSClR5G3bKO-GxXUXulugF6x3CleK31-1JaRbUc6qxtezUWz4G2jEkZyvQf6H4yBNf8myfJj38-OsDsKwdtVdEckuLbguauzcDZTGIojzd33RwqYTkviBsslIqIZURn04fpy9o57sa7zNWa_V7WhSg2fyIdFxdjYaZVilwvl-0CsLHN-7kt2OSReyzyxWWV01q9ntyT4Z72j15Qi5SdW1AX0vq3VZ6Wc3txtUIsXKPGclQshmRLswPnruMlxw5nvkB2fnX3c3Udjnk8q8hBOSwLFpnmhlYHuNESm3-joMIZqT5PF-NdKA6Xm6sbXJB8ub8Hlq5V0K1ZgCirZHmVMD2gH-fAHgptbuuzU1Wu4rBq3ZXo6Ukl-DP5MjF1-m_QOciFYpiqFl29Bq_PndEabssrqoZu-t_GSvhO5KytKh_4Ahd9siz-zRSP_BRuYcAnJCdIJmBw0Ztcbxau70LPgfvAXfcD8eeNnA==)
+
+Taken from <https://vega.github.io/vega/examples/nested-bar-chart/>.
+
+### C4 with PlantUML
+
+<details>
+  <summary>Show code</summary>
+  <div markdown="1">  
+    ```plantuml
+    @startuml "techtribesjs"
+    !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
+    ' uncomment the following line and comment the first to use locally
+    ' !include C4_Container.puml
+    
+    LAYOUT_TOP_DOWN()
+    'LAYOUT_AS_SKETCH()
+    LAYOUT_WITH_LEGEND()
+    
+    
+    Person_Ext(anonymous_user, "Anonymous User")
+    Person(aggregated_user, "Aggregated User")
+    Person(administration_user, "Administration User")
+    
+    System_Boundary(c1, "techtribes.js"){
+        
+        Container(web_app, "Web Application", "Java, Spring MVC, Tomcat 7.x", "Allows users to view people, tribes, content, events, jobs, etc. from the local     tech, digital and IT sector")
+    
+        ContainerDb(rel_db, "Relational Database", "MySQL 5.5.x", "Stores people, tribes, tribe membership, talks, events, jobs, badges, GitHub repos, etc.")
+    
+        Container(filesystem, "File System", "FAT32", "Stores search indexes")
+    
+        ContainerDb(nosql, "NoSQL Data Store", "MongoDB 2.2.x", "Stores from RSS/Atom feeds (blog posts) and tweets")
+    
+        Container(updater, "Updater", "Java 7 Console App", "Updates profiles, tweets, GitHub repos and content on a scheduled basis")
+    }
+    
+    System_Ext(twitter, "Twitter")
+    System_Ext(github, "GitHub")
+    System_Ext(blogs, "Blogs")
+    
+    
+    Rel(anonymous_user, web_app, "Uses", "HTTPS")
+    Rel(aggregated_user, web_app, "Uses", "HTTPS")
+    Rel(administration_user, web_app, "Uses", "HTTPS")
+    
+    Rel(web_app, rel_db, "Reads from and writes to", "SQL/JDBC, port 3306")
+    Rel(web_app, filesystem, "Reads from")
+    Rel(web_app, nosql, "Reads from", "MongoDB wire protocol, port 27017")
+    
+    Rel_U(updater, rel_db, "Reads from and writes data to", "SQL/JDBC, port 3306")
+    Rel_U(updater, filesystem, "Writes to")
+    Rel_U(updater, nosql, "Reads from and writes to", "MongoDB wire protocol, port 27017")
+    
+    Rel(updater, twitter, "Gets profile information and tweets from", "HTTPS")
+    Rel(updater, github, "Gets information about public code repositories from", "HTTPS")
+    Rel(updater, blogs, "Gets content using RSS and Atom feeds from", "HTTP")
+    
+    Lay_R(rel_db, filesystem)
+    
+    @enduml
+    ```
+  </div>
+</details>
+
+![Sample C4 PlantUML diagram](https://kroki.hzdr.de/plantuml/svg/eNqNVU1z2zgMvetXYH2pMqPabbJtZvZUJ06Tdp2PRvJmetJQEmyzpUgtScXx7Ox_L0jJshS3k_pgUeAj8AA8UB-MZdrWpYCRxXxtNc_QfDOj4A8uc1EXCGtrK_PXZKLZZrzidl1ntUGdK2lR2nGuykklmHQuXhtbCJ5Nzv98fedMi-v5pGTGoiZTek4nGJeoxxVhg1dQSzpckhOwa4SlEkJtuFyBIBAwWcBgm2tDKwUUHITKmRBb8tGxPAwQzKdfbxdJmtzepbPbh5vwKHjVmqZxGv99kZxfka01PXxKrtL5xeXFzYyMQXCH2iiZXjzZkEklt6WqTeoSj2A03RlgQYbRUQsO2WqlccUsFh2yszyHFiWX3FjNLKcwO_jAujsSxFuqYZmeqVoWTG_D_G3U79aY2nX0XwD0839dHcINZimrKkI_YAbTqhI8965HZPrMHlkEcaVdza__OY8gUSVtw-n4ye1PXT-Mq7c2rvCPHDdQoaoERtBEjqCVQQT4SA8yfFMZ_aPNx7DUqvS98-0CRziCgpOG6M3191MCBnOrfJID5rMs1CjSIiMe9yg8Zzo0Y5ZlzKCjd72Nv8zh3fhdwzYmN2gO-PknlFhmlMWaUyko-HfznG_GipWDX3J7VWegsVJtFgfUwiUXaHxHKOxHeoGmP47Fx2lyctyjY5DpfA1cFviE5mdpSmX-FXTgRrl0XILgz_oUlVyp2Rkcj48HSfrC3sfxZGppsUQsDISZUCsg2tYc-eLaDaI9DBnWVUF6dGpbNKudFuDUoYyihEgpow5ARdXKJx21Tod1akfV6wBItQxMvsaiFiR6ahZ3HP7vROwGym64bSgkzYoQve3mkqHdJspw06VJBEZn7umyC0gfByO6Fz7NkHG5XCXJXUx4j34-py_Afzarvz7iz3TbPRmzom2dK9hGc1daq3xfv8wnn2dnNIKV0hZOTt68b2N3fgaq2_t6DtvJqYfoCWnDNbpuWpUr0QY7Pn3z9rSlnS728niBeOGU-gL7vrsB_4cu-QPcYQKH5frddPZe94q7JP3uBE1zuVS6bC7b_cx0ZeuLoHO1V6eDDjxkqrZQ1RndsjQQ9FHy88FpaDm-4HUna-90N0y1cVczDbon1xv2viuX65xt0_vuxtyXmrY-oCzoa_gDr6egyQ==)
+
+Taken from <https://github.com/plantuml-stdlib/C4-PlantUML>.
+
+### GraphViz
+
+<details>
+  <summary>Show code</summary>
+    <div markdown="1">
+    {% raw %}
+    ```graphviz
+    digraph G {
+      concentrate=True;
+      rankdir=TB;
+      node [shape=record];
+      140087530674552 [label="title: InputLayer\n|{input:|output:}|{{[(?, ?)]}|{[(?    , ?)]}}"];
+      140087537895856 [label="body: InputLayer\n|{input:|output:}|{{[(?, ?)]}|{[(?,     ?)]}}"];
+      140087531105640 [label="embedding_2: Embedding\n|{input:|output:}|{{(?, ?)}|{    (?, ?, 64)}}"];
+      140087530711024 [label="embedding_3: Embedding\n|{input:|output:}|{{(?, ?)}|{    (?, ?, 64)}}"];
+      140087537980360 [label="lstm_2: LSTM\n|{input:|output:}|{{(?, ?, 64)}|{(?,     128)}}"];
+      140087531256464 [label="lstm_3: LSTM\n|{input:|output:}|{{(?, ?, 64)}|{(?, 32)    }}"];
+      140087531106200 [label="tags: InputLayer\n|{input:|output:}|{{[(?, 12)]}|{[(?    , 12)]}}"];
+      140087530348048 [label="concatenate_1: Concatenate\n|{input:|output:}|{{[(?,     128), (?, 32), (?, 12)]}|{(?, 172)}}"];
+      140087530347992 [label="priority: Dense\n|{input:|output:}|{{(?, 172)}|{(?, 1)    }}"];
+      140087530711304 [label="department: Dense\n|{input:|output:}|{{(?, 172)}|{(?,     4)}}"];
+      140087530674552 -> 140087531105640;
+      140087537895856 -> 140087530711024;
+      140087531105640 -> 140087537980360;
+      140087530711024 -> 140087531256464;
+      140087537980360 -> 140087530348048;
+      140087531256464 -> 140087530348048;
+      140087531106200 -> 140087530348048;
+      140087530348048 -> 140087530347992;
+      140087530348048 -> 140087530711304;
+    }
+    ```
+    {%endraw%}
+  </div>
+</details>
+
+![Sample GraphViz diagram](https://kroki.hzdr.de/graphviz/svg/eNqtk01rwkAQhu_-isVTAxY2m69NJBX6QSnYU71ZkdVdNDRuwmY9SPS_d2NiEnWrFTyEvBOGZyYz79BoIUi6BO8g7wAwT_iccSmIZOFIrFlffROE_9BIhKPnIuIJZWCcLUnKQsHmiaCT4rNpQ4g9x4KuZzsOAuOYzFgcdmUkYxaAD56u5ZBsmPjm2zwqomCbrGXx3m3zfPww6IGBMVG6lrvuEdnDvoMdtybPErq5C9g0oePasAaz1YxRGvHFFAXg7RDo8SVSqb3oAdc2TvHQUwWQrcFb98B7PoaW23QfZ3JVND78Gn1egJasEmwifIY1kZqJax9jrZuwFjI0o3YRbJqVZJH9c4cmapa416djtmwMbVyjCycrF3P1TM0AvDThxSLY6IGq-VJUdffSO_8jVdbz_cbvqYgSEUnlzFfGM_b3qPawiqv1jAWb6VOWEiFX6jJv4Wq8WF3n49Op-3WX1sqqTKw7m1ZW5UWd-9sVS2vpTNyuWO5T58krWZXHLmcd7HKcVazyWla5mn5n9wvGN3i8)
+
+Taken from <https://graphviz.org/Gallery/directed/neural-network.html>.
+
+### BlockDiag
+
+<details>
+  <summary>Show code</summary>
+  <div markdown="1">  
+    ```blockdiag
+    blockdiag {
+      A -> B -> C -> D;
+      A -> E -> F -> G;
+    }
+    ```
+  </div>
+</details>
+
+![Sample Blockdiag diagram](https://kroki.hzdr.de/blockdiag/svg/eNpLyslPzk7JTExXqOZSUFBwVNC1U3ACEc4gwsUaLugKItxAhLs1Vy0Ae3UMLA==)
+
+Taken from <http://blockdiag.com/en/blockdiag/examples.html>.
+
+## Deployment
+The service is provided by HIFIS Software and is hosted entirely on HZDR
+servers.
+It does not share any data with external providers.
+As usual, the deployment can be reproduced via the corresponding
+[project](https://gitlab.hzdr.de/hifis-software-deployment/kroki) - 
+only accessible for employees within Helmhholtz.
+
+## More Examples
+More examples can be found in the
+[GitLab example project](https://gitlab.hzdr.de/examples/kroki).
+
+## Comments and Suggestions
+
+If you have suggestions, questions, or queries, please don't hesitate to write us.
+
+<a href="{% link contact.md %}" 
+                            class="btn btn-outline-secondary"
+                            title="HIFIS Helpdesk"> 
+                            Contact us! <i class="fas fa-envelope"></i></a>