avisi-cloud / structurizr-site-generatr

Static site generator for architecture models created with Structurizr DSL
https://avisi-cloud.github.io/structurizr-site-generatr/
Apache License 2.0
229 stars 35 forks source link

Actual example diagrams from Mermaid are not rendered correctly #241

Closed UBessle closed 1 year ago

UBessle commented 1 year ago

I've activated the GitLab extension for Flexmark markdown converter with property structurizr.markdown.flexmark.extensions

When i extend the sample page 02-markdown-features.md with an actual example from https://mermaid.js.org/syntax/sequenceDiagram.html i'll get a syntax error warning from mermaid

grafik

So the following code is not working

```mermaid
sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts <br/>prevail!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!

Even if it is working perfectly in Mermaid Live Editor
https://mermaid.live/edit#pako:eNptUcFOwzAM_RUv507cCyoCIUCT4ADXXtzEbSLSuKQOqJr276SdMmkSPj35vWfnxUel2ZCq1UzfiYKmJ4dDxLGNbYBcE0Zx2k0YBB680_Qf8chdaW-afdMc2IYaXsl7hhVXYPkXMBIsnO6L2jNPWYRerLakv0p_rdV1GfTsBiuAA7owC9hlYm05mOiwWCiYAt9ZCOLm4B7OAz5QHAf0IJZTZma46-JNM0X6Qed3xbotzVu3GDW8REK5Jpsmp83J1jQdJ7nKk6n95c0H9n6BgdnsblWlRoojOpO_-riKWyWWRmpVnaGhHpOXVrXhlKWYhD-XoFUtMVGl0mRQymVU3aOfc5eME45v5_NtVzz9AZBAmZ8

and on github
```mermaid
sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts <br/>prevail!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!
UBessle commented 1 year ago

I've looked into the problem and the reason is, that Mermaid support in GitLab extension of flexmark markdown converter is a bit outdated.

In the beginning of Mermaid, the Mermaid syntax did enforce, that each statement had to be ended with a semicolon. Later the syntax was simplified and allowed simple line endings to close a statement.

Unfortunately the Mermaid option in the GitLab extension replaces all line endings with spaces in the generated HTML code.

Out of

```mermaid
sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts <br/>prevail!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!;

it will generate

```html
<div class="mermaid">
sequenceDiagram participant Alice participant Bob Alice-&gt;&gt;John: Hello John, how are you? loop Healthcheck John-&gt;&gt;John: Fight against hypochondria end Note right of John: Rational thoughts &lt;br/&gt;prevail! John--&gt;&gt;Alice: Great! John-&gt;&gt;Bob: How about you? Bob--&gt;&gt;John: Jolly good!
</div>

and that's no longer syntactically correct and parseable for Mermaid.

UBessle commented 1 year ago

The workaround until a fix is, to use the old Mermaid syntax with semicolon as statement ending.

```mermaid
sequenceDiagram;
    participant Alice;
    participant Bob;
    Alice->>John: Hello John, how are you?;
    loop Healthcheck;
        John->>John: Fight against hypochondria;
    end;
    Note right of John: Rational thoughts <br/>prevail!;
    John-->>Alice: Great!;
    John->>Bob: How about you?;
    Bob-->>John: Jolly good!;

will be generated to 
sequenceDiagram; participant Alice; participant Bob; Alice->>John: Hello John, how are you?; loop Healthcheck; John->>John: Fight against hypochondria; end; Note right of John: Rational thoughts <br/>prevail!; John-->>Alice: Great!; John->>Bob: How about you?; Bob-->>John: Jolly good!;


and that's working fine with Mermaid
UBessle commented 1 year ago

would be fixed with PR https://github.com/avisi-cloud/structurizr-site-generatr/pull/240