What file formats do you use to manage documents in GitLab? You may use MS Word, Excel, PDF, Markdown and so on. If your reviewer are in your organization, the Markdown is useful. There are some advantages:
- Git manages version history of files.
- GitLab can be browsed with a web browser and markdown files are rendered in your browser.
You may have trouble if you want to insert diagrams.
What application you use to make diagrams?
GitLab can render diagrams in the markdown files. It supports SVG, PNG and any other famous image file formats. It is important that what application to use for making diagrams. Markdown is a simple text file and easily to be updated.
How about a diagram? If the specific application is needed to be updated, it may be hard to be updated.
Documents for the engineer, I recommend the Markdown. With Kroki, you can write diagrams by text.
GitLab supports Kroki
GitLab supports Kroki. Kroki presents the API for generating images from text. For example, you write the UML with plant UML syntax, Kroki generates the UML from it.
One of famous text based UML generator is PlantUML, Kroki supports it. If you write UML with PlantUML format in the markdown file, GitLab will show the rendered UML. GitLab generates the UML image by using Kroki.
Supported syntax by Kroki is not only PlantUML. There are many syntax that Kroki supports. Please see official site.
Install Kroki on your server
Kroki can be installed on your server or cloud instance with a docker. Create
version: "3" services: kroki: image: yuzutech/kroki depends_on: - blockdiag - mermaid - bpmn - excalidraw environment: - KROKI_BLOCKDIAG_HOST=blockdiag - KROKI_MERMAID_HOST=mermaid - KROKI_BPMN_HOST=bpmn - KROKI_EXCALIDRAW_HOST=excalidraw ports: - "8000:8000" blockdiag: image: yuzutech/kroki-blockdiag expose: - "8001" mermaid: image: yuzutech/kroki-mermaid expose: - "8002" bpmn: image: yuzutech/kroki-bpmn expose: - "8003" excalidraw: image: yuzutech/kroki-excalidraw expose: - "8004" Run the daemon.
% docker-compose up -d
Configure the GitLab
Configure the GitLab to access to Kroki. Select “General” in “Settings” in “Admin Area”.  Click “Expand” button of “Kroki”.  Turn on “Enable Kroki” check box.  Enter the URL to Kroki in the docker container into the “Kroki URL” field. The port number is
8000. The port number is specified in
docker-compose.ymlfile.  Turn on “Additional diagram formats” if you have not special reason.  Click the “Save changes” button.
There is a PlantUML option under Kroki option. Kroki supports PlantUML so you need not configure this option.
Create the sample markdown file in your git repository.
WebIDE also also render the UML in the preview.
# Sample Markdown Write the UML in the code block. You need specify the tool generates the image. If the tools is missing, render the block as simple code block. ## Sample Chart ### PlantUML ```plantuml @startuml GitLab -> Kroki: Request rendering Kroki -> PlantUML: Request rendering PlantUML -> Kroki: Image Kroki -> GitLab: Image @enduml ``` ### Mermaid ```mermaid sequenceDiagram GitLab->>Kroki: Request rendering Kroki->>Mermaid: Request rendering Mermaid-->>Kroki: Image Kroki-->>GitLab: Image ```