Differences in `label: ` syntax?

[stdedos]

Hellou there,

Related to this Mermaid discussion: https://github.com/orgs/mermaid-js/discussions/7332

I’m seeing different rendering in mkdocs (via mkdocs-mermaid2) vs GitHub / https://mermaid.live/edit for blank lines inside a shape label:.
tl;dr it seems that there is no way to render one new line between 📋 List and the steps - even when <br/> is used

I realize that mkdocs does NOT render according to Commonmark rules. Also, I am new to mkdocs - so my config might not be the best.

Here's my gfm comment source:

For this diagram

````md
```mermaid
flowchart LR
    List@{ shape: braces, label: "📋 List

    ☐ Step A
    ☑ Step B
    ☑ Step C
    ☐ Step D
    ☐ Step E
    ☐ Step F
    ☐ Step G" }
```
````

I want to add exactly one empty line between `📋 List` and the steps.

All my attempts, however, give different results:

1. ````md
   ```mermaid
   flowchart LR
       List@{ shape: braces, label: "📋 List
 
       ☐ Step A
       ☑ Step B
       ☑ Step C
       ☐ Step D
       ☐ Step E
       ☐ Step F
       ☐ Step G" }
   ```
   ````
 
   ```mermaid
   flowchart LR
       List@{ shape: braces, label: "📋 List
 
       ☐ Step A
       ☑ Step B
       ☑ Step C
       ☐ Step D
       ☐ Step E
       ☐ Step F
       ☐ Step G" }
   ```

2. ````md
   ```mermaid
   flowchart LR
       List@{ shape: braces, label: "📋 List<br>
 
       ☐ Step A
       ☑ Step B
       ☑ Step C
       ☐ Step D
       ☐ Step E
       ☐ Step F
       ☐ Step G" }
   ```
   ````
 
   ```mermaid
   flowchart LR
       List@{ shape: braces, label: "📋 List<br>
 
       ☐ Step A
       ☑ Step B
       ☑ Step C
       ☐ Step D
       ☐ Step E
       ☐ Step F
       ☐ Step G" }
   ```

3. ````md
   ```mermaid
   flowchart LR
       List@{ shape: braces, label: "📋 List<br><br>
 
       ☐ Step A
       ☑ Step B
       ☑ Step C
       ☐ Step D
       ☐ Step E
       ☐ Step F
       ☐ Step G" }
   ```
   ````
 
   ```mermaid
   flowchart LR
       List@{ shape: braces, label: "📋 List<br><br>
 
       ☐ Step A
       ☑ Step B
       ☑ Step C
       ☐ Step D
       ☐ Step E
       ☐ Step F
       ☐ Step G" }
   ```


4. ````md
   ```mermaid
   flowchart LR
       List@{ shape: braces, label: "📋 List
       <br>
       ☐ Step A
       ☑ Step B
       ☑ Step C
       ☐ Step D
       ☐ Step E
       ☐ Step F
       ☐ Step G" }
   ```
   ````
   ```mermaid
   flowchart LR
       List@{ shape: braces, label: "📋 List
       <br>
       ☐ Step A
       ☑ Step B
       ☑ Step C
       ☐ Step D
       ☐ Step E
       ☐ Step F
       ☐ Step G" }
   ```

... except 3 and 4 (which both render 3 `<br/>`s)

I have looked at the help:
* There is no mentioning of `label:` parameter in `shape:`, and
* In https://mermaid.ai/open-source/syntax/flowchart.html#parameters of Icon Shape, it merely says `label: The text label associated with the icon. This can be any string. If not defined, no label will be displayed.` - without specifying what syntax the `label:` has.

According to Commonmark rules, a newline with an empty line is enough to generate a paragraph.

I am very new to Mermaid - so it might be mentioned somewhere else.

Thank you for your time and effort

Environment:

$ uv pip list | grep mkdocs-
mkdocs-autorefs            1.4.3
mkdocs-get-deps            0.2.0
mkdocs-material            9.7.1
mkdocs-material-extensions 1.3.1
mkdocs-mermaid2-plugin     1.2.3

# mkdocs.yml
site_name: A

docs_dir: docs
theme:
  name: material
  features:
    - content.code.annotate

plugins:
  - search
  - mermaid2:
      # Different from the 10.7.0 default
      version: 11.12.2
  # - commonmark
  # Stay on `mkdocs==1.4.3` (which forces quite a few downgrades), or
  # https://github.com/mkdocs/mkdocs/issues/1835#issuecomment-1664770402, or
  # "just don't do it"
  - mkdocstrings:
      handlers:
        python:
          options:
            docstring_style: restructuredtext
            show_source: true

markdown_extensions:
  - tables
  - toc:
      permalink: true
  - pymdownx.inlinehilite
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:mermaid2.fence_mermaid_custom
  - pymdownx.highlight

[github-actions]

Thank you for your contribution! This is very appreciated.

[fralau]

@stdedos Thank you for your comment. This issue is a little out of my area of expertise, and asking the Mermaid team was the right thing to do.

Mkdocs-Mermaid2 packages the Mermaid code into HTML (and calls to Javascript) and inserts this into the final HTML page, so that it can be later executed on "the host" (which is the browser that the user uses to reade the page).

My best recommendation would be that you first resolve the problem entirely within the Mermaid ecosystem (especially the live editor, which is a sort of "reference implementation") so that you know what result you want to get, and how to get it. Once that is done, it is demonstrated that there is a valid path from your intention to your result.

Then you would apply that solution to the Mkdocs-Mermaid2 ecosystem and see if you can make it work. It might work out of the box; or there might be unavoidable issues of escaping, HTML tags, css, etc., that would require tweaking.

I cannot guarantee that you will get the result expected. To give you some background context, the purpose of Mkdocs-Mermaid2 has been to provide a direct bridge between the Markdown and Mermaid languages, over the "chasm" of HTML tags, Javascript and css. Ideally, it should be a solid, stable platform on which heavy trucks can travel; in practice, it is more like a wooden bridge held by ropes, and one has to exert some caution. There are interactions and side-effects that none of us fully master.

However, it's definitely worth trying.

I hope this helps.

[stdedos]

My best recommendation would be that you first resolve the problem entirely within the Mermaid ecosystem (especially the live editor, which is a sort of "reference implementation") so that you know what result you want to get, and how to get it. Once that is done, it is demonstrated that there is a valid path from your intention to your result.

My problem is that mkdocs-mermaid2-plugin does not render the same as the reference implementation 😅

I cannot take screenshots anymore (and mkdocs does not render Here's my gfm comment source: the way that gfm does) - but mkdocs-mermaid2-plugin does NOT add a newline between 📋 List and the steps. None of the 4 charts that are shown in the https://github.com/orgs/mermaid-js/discussions/7332 render that empty line that I want i.e. this

As you saw, I also updated the mermaid to match the live editor

  - mermaid2:
      # Different from the 10.7.0 default
      version: 11.12.2

compared to "known good" that mkdocs-mermaid2-plugin provides

---

I would be suspecting that, even though I write this

mermaid via mkdocs etc in the end does not receive the same text.

However I don't know how I could verify that 😅

---

In any case, thank you so much for the effortless-to-use plugin you have created - and the way you are engaging with the issues 😊 🙏

[fralau]

You're very welcome 🙂. I am glad that the plugin works with little friction.

If you managed to get the effect you want with the Live Editor then we have a point of comparison.

In principle, Mkdocs-Macros does not touch the Mermaid code.

A few heuristic hypotheses:

1. Newlines are a little tricky because some transformations such as strip() or conversions (from Markdown to HTML), can cause the loss of newlines. I don't see how that could be, but that could be the culprit.
2. A difference in Javascript version of libraries? But we could exclude that, from the data you gave me.
3. Other influencing factors, such as css (which could in theory change positioning)?

There is no way to be sure, unless we investigate further.

Would you be able to produce a Minimal Reproducible Example (MRE), removing all that is not strictly the issue?

[stdedos]

Idk if you can call it "MRE", but here is my example:

Source (same as my https://github.com/orgs/mermaid-js/discussions/7332 response, slightly edited for rendering)

For this diagram

````md
```mermaid
flowchart LR
    List@{ shape: braces, label: "📋 List

    ☐ Step A
    ☑ Step B
    ☑ Step C
    ☐ Step D
    ☐ Step E
    ☐ Step F
    ☐ Step G" }
```
````

I want to add exactly one empty line between `📋 List` and the steps.

All my attempts, however, give different results:

1.
````md
```mermaid
flowchart LR
    List@{ shape: braces, label: "📋 List

    ☐ Step A
    ☑ Step B
    ☑ Step C
    ☐ Step D
    ☐ Step E
    ☐ Step F
    ☐ Step G" }
```
````

```mermaid
flowchart LR
    List@{ shape: braces, label: "📋 List

    ☐ Step A
    ☑ Step B
    ☑ Step C
    ☐ Step D
    ☐ Step E
    ☐ Step F
    ☐ Step G" }
```

2.
````md
```mermaid
flowchart LR
    List@{ shape: braces, label: "📋 List<br>

    ☐ Step A
    ☑ Step B
    ☑ Step C
    ☐ Step D
    ☐ Step E
    ☐ Step F
    ☐ Step G" }
```
````

```mermaid
flowchart LR
    List@{ shape: braces, label: "📋 List<br>

    ☐ Step A
    ☑ Step B
    ☑ Step C
    ☐ Step D
    ☐ Step E
    ☐ Step F
    ☐ Step G" }
```

3.
````md
```mermaid
flowchart LR
    List@{ shape: braces, label: "📋 List<br><br>

    ☐ Step A
    ☑ Step B
    ☑ Step C
    ☐ Step D
    ☐ Step E
    ☐ Step F
    ☐ Step G" }
```
````

```mermaid
flowchart LR
    List@{ shape: braces, label: "📋 List<br><br>

    ☐ Step A
    ☑ Step B
    ☑ Step C
    ☐ Step D
    ☐ Step E
    ☐ Step F
    ☐ Step G" }
```

4.
````md
```mermaid
flowchart LR
    List@{ shape: braces, label: "📋 List
    <br>
    ☐ Step A
    ☑ Step B
    ☑ Step C
    ☐ Step D
    ☐ Step E
    ☐ Step F
    ☐ Step G" }
```
````
```mermaid
flowchart LR
    List@{ shape: braces, label: "📋 List
    <br>
    ☐ Step A
    ☑ Step B
    ☑ Step C
    ☐ Step D
    ☐ Step E
    ☐ Step F
    ☐ Step G" }
```

... except 3 and 4 (which both render 3 `<br/>`s)

I have looked at the help:
* There is no mentioning of `label:` parameter in `shape:`, and
* In https://mermaid.ai/open-source/syntax/flowchart.html#parameters of Icon Shape, it merely says `label: The text label associated with the icon. This can be any string. If not defined, no label will be displayed.` - without specifying what syntax the `label:` has.

According to Commonmark rules, a newline with an empty line is enough to generate a paragraph.

I am very new to Mermaid - so it might be mentioned somewhere else.

Thank you for your time and effort

And here is how my rendering looks like

If you look at all the diagrams, no-one has an empty line (like the image above from https://mermaid.live/ shows)