Help with mini Quarto ELK Mermaid layout

[anaitab]

Description

Thanks for reading. I am a very beginner user, looking for help with the ELK layout for Mermaid.

The ELK layout does not show up on my Mermaid diagram. However, when inspecting index.html with the devtools console mermaid.mermaidAPI.getConfig(), I see some ELK settings, but I don't know enough to determine whether they are correct.

The Mermaid diagram is defined in a separate file, and injected via an 'include' directive. I was not able to upload any Quarto Markdown .qmd files to this discussion, but I made a github mini rep with my index.qmd, _quarto.yml, and three companion .qmd files.

https://github.com/anaitab/mermaid-elk

Here is my index.qmd:

---
title: "Mermaid-ELK Test"
format:
  html:
    engine: knitr

---
# Map

{{< include Diagram.qmd >}}

Here is my included Diagram.qmd with my mermaid config settings. I have 'elk' everywhere, in case it would by chance make it work (a novice here), but it does not.
`

%%{init: {"theme":"base","fontSize":"0.6em","themeVariables":{"background":"#B8A539","htmlLabels":true},"layout":"elk","elk":{"mergeEdges":true,"nodePlacementStrategy":"simple"},"securityLevel":"loose","flowchart":{"nodeSpacing":10,"rankSpacing":200, "wrappingWidth":230, "padding":3, "defaultRenderer":"elk","layoutAlgorithm":"elk","mergeEdges":true,"nodePlacementStrategy":"simple","htmlLabels":true},"er":{"htmlLabels":true,"layoutDirection":"LR","padding":3,"wrappingWidth":230,"defaultRenderer":"elk","layoutAlgorithm":"elk","mergeEdges":true,"nodePlacementStrategy":"simple"}}}%%
flowchart LR
  index["Index"]
  number1["Number 1"]
  number2["Number 2"]
  index --> number1
  index --> number2
  click index "index.html"
  click number1 "number1.html"
  click number2 "number2.html"

`

Here is a screenshot of how the rendered mermaid diagram looks like; no elk layout.

[mcanouil]

@anaitab

Important

Accessibility: To improve accessibility, please add alternative text to your screenshots. This helps all users, including those using screen readers, to understand the context of the images. A brief description can make a big difference! See Good Alt Text, Bad Alt Text — Making Your Content Perceivable.

---

Could you properly format your post using code blocks for code and terminal outputs? Thanks.
If your code contains code blocks, you need to enclose it using more backticks, i.e., usually four ````.
See https://quarto.org/bug-reports.html#formatting-make-githubs-markdown-work-for-us.

[anaitab]

thanks for your suggestions to better present my question

[mcanouil]

I don't know what is the mermaid.js version required for this, but for now in development version of Quarto (1.9) with mermaid.js 11.12.0, this does not seem to work.

Regarding all your theming, these are in conflict, i.e., overwritten by Quarto theming system: https://quarto.org/docs/authoring/diagrams.html#mermaid-theming

---
title: "Reproducible Quarto Document"
format: html
---

```{mermaid}
---
config:
  layout: elk
  elk:
    mergeEdges: true
    nodePlacementStrategy: LINEAR_SEGMENTS
---
flowchart LR
  A[Start] --> B{Choose Path}
  B -->|Option 1| C[Path 1]
  B -->|Option 2| D[Path 2]
```

[Steinthal]

ELK layout is not working for Mermaid version 11.*. According to the discussion at that issue, you need to have the engine loaded and registered.

Try:

---
title: "Reproducible Quarto Document"
format: 
  html:
    include-in-header: 
      text: |
        <script type="module">
        import elkLayouts from 'https://cdn.jsdelivr.net/npm/@mermaid-js/layout-elk@0/dist/mermaid-layout-elk.esm.min.mjs';
        mermaid.registerLayoutLoaders(elkLayouts);
        </script>
---

```{mermaid}
---
config:
  layout: elk
  elk:
    mergeEdges: true
    nodePlacementStrategy: LINEAR_SEGMENTS
---
flowchart LR
  A[Start] --> B{Choose Path}
  B -->|Option 1| C[Path 1]
  B -->|Option 2| D[Path 2]
```

You then get this:

[anaitab]

Wow Steinthal. It is so simple. And it works perfectly! I also tried with the include directive, and it works as well. And I have spent weeks down the rabbit hole trying to find a way to make it work. A million Thanks!

I have uploaded this to my mini GitHub example with the 'include'.

[anaitab]

I was able to change the node padding, but not the node or rank spacing. Do you know if this is because of ELK, or do I have the syntax wrong?

```{mermaid}
---
config:
  layout: elk
  elk:
    mergeEdges: true
    nodePlacementStrategy: LINEAR_SEGMENTS
  flowchart:
    rankSpacing: 150
    nodeSpacing: 150
    padding: 5

---
flowchart LR
  A[Start] --> B{Choose Path}
  B -->|Option 1| C[Path 1]
  B -->|Option 2| D[Path 2]

[mcanouil]

Better to check with mermaid.js documentation.

[anaitab]

Thanks. In the example, rank and node spacing work when the layout is Dagre, but not when it is elk.

[anaitab]

Quarto Version: 1.8.26
Mermaid Version: 11.12.1

I checked the Mermaid and Quarto documentation and other forums thoroughly before coming here to ask for help. I did not find the Mermaid Live Tools very helpful for my questions. But again, I am a very beginner user.

Anyway, I am sharing some styling options I figured out through experimentation once I got unstuck (a little help can go a long way) as a way to say thanks.

First, in Quarto frontmatter, to disable Quarto built in theme features, I used: format -> html: -> minimal: true. Then, I was able to apply some Mermaid styling features.

Front Matter:

---
title: "Mermaid Charts with Quarto"
format: 
  html:
    minimal: true
    include-in-header: 
      text: |
        <script type="module">
        import elkLayouts from 'https://cdn.jsdelivr.net/npm/@mermaid-js/layout-elk@0/dist/mermaid-layout-elk.esm.min.mjs';
        mermaid.registerLayoutLoaders(elkLayouts);
        </script>
---

Example 1.
Mermaid with default (Dagre) layout
Config: Tunable node padding, rankSpacing, and nodeSpacing
I also used classDef to set node styles and linkStyle to set link (arrow) styles.

---
config:
  themeVariables:
    fontSize: 0.8rem
  flowchart:
    rankSpacing: 10
    nodeSpacing: 20
    padding: 10
---
flowchart LR
  A[Start] --> B{Choose Path}
  B -->|Option 1| C[Path 1]
  B -->|Option 2| D[Path 2]
  
%% Styles
classDef default fill:white,stroke:#333,stroke-width:2px;
linkStyle default stroke:black, stroke-width:2px;

Example 1 produces a diagram like this one:

Example 2.
Mermaid with ELK layout
Tunable node padding
(rankSpacing and nodeSpacing settings are ignored)
clasDef is used to define node styles
linkStyle is used to define link(lines, arrows) styles
`

---
config:
  themeVariables:
    fontSize: 0.8rem
  layout: elk
  elk:
    mergeEdges: true
    nodePlacementStrategy: LINEAR_SEGMENTS
  flowchart:
    rankSpacing: 150
    nodeSpacing: 150
    padding: 5
---
flowchart LR
  A[Start] --> B{Choose Path}
  B -->|Option 1| C[Path 1]
  B -->|Option 2| D[Path 2]

%% Styles
classDef default fill:white,color:blue,stroke:#006699,stroke-width:2px;
linkStyle default stroke:#006699, stroke-width:1px;

Example 2 produces a diagram like this one:

[Steinthal]

anaitab, you don't need to disable Quarto's built-in theme features. You can simply apply styling to your mermaid diagrams.

Regarding rankSpacing and nodeSpacing: Dagre and ELK seem to pusue different goals:

• Dagre (default): This is the classic layout algorithm that has been used in Mermaid for a long time. It provides a good balance of simplicity and visual clarity, making it ideal for most diagrams.
• ELK: For those who need more sophisticated layout capabilities, especially when working with large or intricate diagrams, the ELK (Eclipse Layout Kernel) layout offers advanced options. It provides a more optimized arrangement, potentially reducing overlapping and improving readability. This is not included out the box but needs to be added when integrating mermaid for sites/applications that want to have elk support.
  Source: mermaid documentation

Try experimenting with both and look what suits you best:

---
title: "Test"
format:
  html:
    include-in-header: 
      text: |
        <script type="module">
        import elkLayouts from 'https://cdn.jsdelivr.net/npm/@mermaid-js/layout-elk@0/dist/mermaid-layout-elk.esm.min.mjs';
        mermaid.registerLayoutLoaders(elkLayouts);
        </script>
---

```{mermaid}
---
config:
  flowchart:
    nodeSpacing: 50
    rankSpacing: 50
    padding: 5
  look: handDrawn
  theme: forest
  layout: elk
  elk:
    mergeEdges: true
    nodePlacementStrategy: LINEAR_SEGMENTS
---
flowchart LR
  A[Start] ----> B{**Choose**<br/>Path}:::main
  B -- "Option 1" --> C[Path 1]:::data --> E["Test"]
  B -->|Option 2| D[Path 2]:::data --> E

classDef main fill:#4472c4,stroke:#2f5597,color:white
classDef data fill:#70ad47,stroke:#507e32,color:white
```

```{mermaid}
---
config:
  flowchart:
    nodeSpacing: 40
    rankSpacing: 30
    padding: 5
  themeVariables:
    fontSize: 0.8rem  
  look: handDrawn
  theme: default
---
flowchart LR
  A[Start] --> B{Choose<br/>**Path**}:::main
  B -->|Option 1| C[Path 1]:::data ----> E["Test"]
  B -->|Option 2| D[Path 2]:::data ----> E

%% Styles
classDef main fill:#4472c4,stroke:#2f5597,color:white
classDef data fill:#70ad47,stroke:#507e32,color:white
```

That looks like this:

Experiment with the settings: Remove the padding and see how the ELK diagrams changes. Add hyphens to the arrows with the default layout and see what that changes. You won't find anything in the documentation but simply need to play around with a "real" diagram to learn.

[anaitab]