From 2c21db7f117c996f26d946c9e764214b61629acf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Etxaniz=20Errazkin=2C=20I=C3=B1aki?=
<inaki.etxaniz@tecnalia.com>
Date: Thu, 6 Mar 2025 14:16:04 +0100
Subject: [PATCH] Update 2 files
- /including_wrong.puml
- /README.md
---
README.md | 79 +++++++++++++++++++++++---------------------
including_wrong.puml | 1 +
2 files changed, 42 insertions(+), 38 deletions(-)
create mode 100644 including_wrong.puml
diff --git a/README.md b/README.md
index 3162ca4..79a6b8b 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,8 @@
-# PlantUML includes
+# PlantUML in GitLab
Utility project to test PlantUML files rendering and the "!include" directive in these files, that are used in the UML diagrams of the EMERALD project.
-## !include in puml files
-The typical "!include" directive of PlantUML (that search files in folders) doesn't work in Gitlab (see [Wiki Page Plantuml using !include](https://gitlab.com/gitlab-org/gitlab/-/issues/28847)). A workaround is to place the files in some url publicly available.
+## Problem of "!include" clause in puml files
+The typical "!include" directive of PlantUML (that search files in folders) doesn't work in Gitlab (see [Wiki Page Plantuml using !include](https://gitlab.com/gitlab-org/gitlab/-/issues/28847)). The renderer is a separate server that is unable to find the included files. A workaround is to place the files in some url publicly available.
The UML files of EMERALD typically include several common files to define common graphical elements (arrows, colors, names, etc.). For example:
@@ -10,59 +10,62 @@ The UML files of EMERALD typically include several common files to define common
@startuml
RCM Sequence Diagram
-**!include ..\roles.wsd**
-**!include ..\color_pallette.wsd**
+!include ..\roles.wsd
+!include ..\color_pallette.wsd
[..]
@enduml
```
-## PlantUML blocks
-PlantUML blocks (**```plantuml** ... **```**) inside in markdown files didn't render in [Tecnalia's Gitlab](git.code.tecnalia.dev) (self-managed version), unlike in the Gitlab server where this is configured by default.
-After completing the integration, PlantUML converts plantuml blocks to an HTML image tag, with the source pointing to the PlantUML instance. And the PlantUML diagram delimiters **@startuml/@enduml** aren’t required anymore, as these are replaced by the **plantuml** block.
+## PlantUML blocks in self-managed GitLab installations
+PlantUML blocks (**"```plantuml** ... **```"**) inside markdown files didn't render in [Tecnalia's Gitlab](git.code.tecnalia.dev) (self-managed version), unlike in the Gitlab server (see, for example https://gitlab.com/schurzi/playground/-/blob/main/markdown.md), where this is configured by default.
+You need to install a separate PlantUML server, ans configure Gitlab to connect to it. After completing the integration, PlantUML converts plantuml blocks to an HTML image tag, with the source pointing to the PlantUML instance. The PlantUML diagram delimiters **@startuml/@enduml** aren’t required anymore, as these are replaced by the **plantuml** block.
In markdown files (*.md):
-
-**```plantuml**
+```
+```plantuml
Bob -> Alice : hello
Alice -> Bob : hi
-**```**
-For additional acceptable extensions, review the languages.yaml file.
+```
+```
-**07/2024**: This was solved [installing](https://docs.gitlab.com/administration/integration/plantuml/#configure-your-plantuml-server) the corresponding UML server and configuring git.code.tecnalia.dev to connect to it and finally render the plantUML text files as diagrams.
+**UPDATED: Jul/2024**: This was solved [installing](https://docs.gitlab.com/administration/integration/plantuml/#configure-your-plantuml-server) the corresponding UML server and configuring git.code.tecnalia.dev to connect to it and finally render the plantUML text files as diagrams.
+Examples:
+- https://git.code.tecnalia.dev/emerald/public/puml-includes/-/blob/master/markdown_uml_1.md Uses "!include http..." in a markdown (*.md) file
+- https://git.code.tecnalia.dev/emerald/public/puml-includes/-/blob/master/markdown_uml_2.md Uses "::include{file=roles.puml}" in a markdown (*.md) file
-## PlantUML files
+## PlantUML files in GitLab
PlantUML files (*.uml, *.puml...) not rendering in GitLab repos was a long-time known issue (https://gitlab.com/gitlab-org/gitlab/-/issues/17325). The workaround for this could be to check out the repos locally and see the figures using Visual Studio Code with a PlantUML plugin or similar tools.
-**02/2025**: It has been finally solved and included in the [release 19.7](https://gitlab.com/groups/gitlab-org/-/milestones/108) (see [merge request 179301](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/179301)).Now the .pu or .puml files are rendered (when PlantUML integration is enabled) on the gitlab instance. It adds a rich view for graph files. Supported extensions are:
-mermaid
-plantuml
-pu
-puml
-iuml
-d2
-dot
-gv
-noml
-vg
-vl
-
-(Example: https://gitlab.com/schurzi/playground/-/blob/main/plantuml_include/included_part.iuml renders the diagram)
-
-Hopefully, this feature will be automatically translated to Tecnalia's Gitlab when the release (actual version is [v17.8.2](https://git.code.tecnalia.dev/help)) is updated.
-
-(Example: https://git.code.tecnalia.dev/emerald/public/puml-includes/-/blob/master/testDiagram.puml renders only text)
-
-**03/2025**: Updated to GitLab Community Edition v17.9.1
+**UPDATED: Feb/2025**: This has been finally solved and included in the [release 19.7](https://gitlab.com/groups/gitlab-org/-/milestones/108) (see [merge request 179301](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/179301)).Now the **.pu** or **.puml** files are rendered (when PlantUML integration is enabled) on the GitLab instance. It adds a rich view for graph files. Supported extensions are:
+mermaid
+plantuml
+pu
+puml
+iuml
+d2
+dot
+gv
+noml
+vg
+vl
+
+Hopefully, this feature will be automatically translated to Tecnalia's Gitlab when the release is updated (actual version is [v17.8.2](https://git.code.tecnalia.dev/help)).
+
+Examples:
+- https://gitlab.com/schurzi/playground/-/blob/main/plantuml_include/included_part.iuml renders the diagram
+- https://git.code.tecnalia.dev/emerald/public/puml-includes/-/blob/master/testDiagram.puml renders only text
+
+**UPDATED: Mar/2025**: Tecnalia's GitLab updated to Community Edition v17.9.1
Now, the puml files render as diagrams!!
Examples:
-https://git.code.tecnalia.dev/emerald/public/puml-includes/-/blob/master/testDiagram.puml
+- https://git.code.tecnalia.dev/emerald/public/puml-includes/-/blob/master/testDiagram.puml
-https://git.code.tecnalia.dev/emerald/public/puml-includes/-/blob/master/included_part.iuml
+- https://git.code.tecnalia.dev/emerald/public/puml-includes/-/blob/master/included_part.iuml
-https://git.code.tecnalia.dev/emerald/public/puml-includes/-/blob/master/bad_including.puml (includes a wrong ```!including``` clause, and gives an error :-())
+- https://git.code.tecnalia.dev/emerald/public/puml-includes/-/blob/master/bad_including.puml (includes a wrong ```!including``` clause, and gives an error :-())
-https://git.code.tecnalia.dev/emerald/public/puml-includes/-/blob/master/including.puml (includes a correct (https://) ```!including``` clause!)
\ No newline at end of file
+- https://git.code.tecnalia.dev/emerald/public/puml-includes/-/blob/master/including.puml (includes a correct (https://) ```!including``` clause!)
\ No newline at end of file
diff --git a/including_wrong.puml b/including_wrong.puml
new file mode 100644
index 0000000..195859b
--- /dev/null
+++ b/including_wrong.puml
@@ -0,0 +1 @@
+!include included_part.iuml
\ No newline at end of file
--
GitLab