Add support for mermaid diagrams #377

Weibye · 2022-05-29T08:47:07Z

What

Mermaid is a framework that lets you create diagrams and charts using various snippets of code
This change adds support for mermaid in the book-section-template

Why

A lot of the learning materials would be easier to comprehend if accompanied by visual aides
Statically rendered images will quickly become outdated and are hard to maintain (unless some automated setup)
Maintaining these diagrams would be the same as maintaining the text they accompany
~~Would help solve Add breakout diagram to ECS chapter introduction #365~~
- ^ On further exploration, mermaid seems to be unfit to solve this particular diagram or diagrams of equal size / complexity

Usage

To create mermaid diagrams in the book-section templates

{% mermaid() %}
   // mermaid code goes here
{% end %}

Example:

{% mermaid() %}
stateDiagram-v2
    state if_state <<choice>>
    [*] --> IsPositive
    IsPositive --> if_state
    if_state --> False: if n < 0
    if_state --> True : if n >= 0
{% end %}

Result:

stateDiagram-v2
    state if_state <<choice>>
    [*] --> IsPositive
    IsPositive --> if_state
    if_state --> False: if n < 0
    if_state --> True : if n >= 0

Feedback wanted

Do we want the mermaid support added in the layouts/base.html instead, so that we can put diagrams anywhere on the site? I'm sure it could be useful in various news or update posts down the line

DJMcNab · 2022-05-29T08:54:13Z

templates/book-section.html

 <script src="/optional-helpers.js"></script>
+<!-- When this javascript is loaded and initialized it will look for divs with the class `mermaid`
+it will replace the content of those divs with the generated mermaid content-->
+<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>


We shouldn't be pulling from a cdn here

Do you have a suggestion for a better solution?

Changed to use a local version of mermaid instead of fetching from cdn

DJMcNab · 2022-05-29T08:54:51Z

templates/book-section.html

 <script src="/optional-helpers.js"></script>
+<!-- When this javascript is loaded and initialized it will look for divs with the class `mermaid`
+it will replace the content of those divs with the generated mermaid content-->
+<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>


We shouldn't block page paint on mermaid loading and being parsed.

I've removed the block-on-load

Weibye · 2022-05-29T09:36:31Z

With mermaid I'm able to produce the following diagram:

It's not as pretty nor informative as what @doup made, so I'm going to dig a bit into layout or coloring to see what is possible

flowchart LR

  subgraph World
    direction LR

    subgraph Resources
      direction TB
      r0(Input)
      r1(AssetServer)
      r2(Scoreboard)
    end

    subgraph Entities
      direction TB
      subgraph #1 Paddle
        direction LR
        c1_0(Paddle)
        c1_1(Sprite)
        c1_2(Transform)
        c1_3(Collider)
      end
      subgraph #2 Ball
        direction LR
        c2_0(Ball)
        c2_1(Sprite)
        c2_2(Transform)
        c2_3(Velocity)
      end
      subgraph #3 Score
        direction LR
        c3_0(Text)
        c3_1(Style)
      end

      subgraph #4 Top-Wall
        direction LR
        c4_0(Sprite)
        c4_1(Transform)
        c4_2(Collider)
      end

      subgraph #5 Right-Wall
        direction LR
        c5_0(Sprite)
        c5_1(Transform)
        c5_2(Collider)
      end

      subgraph #6 Bottom-Wall
        direction LR
        c6_0(Sprite)
        c6_1(Transform)
        c6_2(Collider)
      end

      subgraph #7 Left-Wall
        direction LR
        c7_0(Sprite)
        c7_1(Transform)
        c7_2(Collider)
      end

      subgraph #8 Brick
        direction LR
        c8_0(Brick)
        c8_1(Sprite)
        c8_2(Transform)
        c8_3(Collider)
      end

      subgraph #...
        direction LR
        c9_0(...)
      end


    end
  end

  subgraph Systems
    direction LR

    subgraph setup
      direction LR
      s0_0(AssetServer)
    end

    subgraph apply_velocty
      direction LR
      s1_0(Transform)
      s1_1(Velocity)
    end

    subgraph paddle_movement
      direction LR
      s2_0(Input)
      s2_1(Paddle)
      s2_1(Transform)
    end

    subgraph ball_collision
      direction LR
      s3_0(Scoreboard)
      s3_1(Ball)
      s3_2(Brick)
      s3_3(Collider)
      s3_4(Transform)
      s3_5(Velocity)
    end

    subgraph scoreboard
      direction LR
      s4_0(Scoreboard)
      s4_1(Text)
    end

  end

  Systems<-->World

Source code:


  flowchart LR

  subgraph World
    direction LR

    subgraph Resources
      direction TB
      r0(Input)
      r1(AssetServer)
      r2(Scoreboard)
    end

    subgraph Entities
      direction TB
      subgraph #1 Paddle
        direction LR
        c1_0(Paddle)
        c1_1(Sprite)
        c1_2(Transform)
        c1_3(Collider)
      end
      subgraph #2 Ball
        direction LR
        c2_0(Ball)
        c2_1(Sprite)
        c2_2(Transform)
        c2_3(Velocity)
      end
      subgraph #3 Score
        direction LR
        c3_0(Text)
        c3_1(Style)
      end

      subgraph #4 Top-Wall
        direction LR
        c4_0(Sprite)
        c4_1(Transform)
        c4_2(Collider)
      end

      subgraph #5 Right-Wall
        direction LR
        c5_0(Sprite)
        c5_1(Transform)
        c5_2(Collider)
      end

      subgraph #6 Bottom-Wall
        direction LR
        c6_0(Sprite)
        c6_1(Transform)
        c6_2(Collider)
      end

      subgraph #7 Left-Wall
        direction LR
        c7_0(Sprite)
        c7_1(Transform)
        c7_2(Collider)
      end

      subgraph #8 Brick
        direction LR
        c8_0(Brick)
        c8_1(Sprite)
        c8_2(Transform)
        c8_3(Collider)
      end

      subgraph #...
        direction LR
        c9_0(...)
      end


    end
  end

  subgraph Systems
    direction LR

    subgraph setup
      direction LR
      s0_0(AssetServer)
    end

    subgraph apply_velocty
      direction LR
      s1_0(Transform)
      s1_1(Velocity)
    end

    subgraph paddle_movement
      direction LR
      s2_0(Input)
      s2_1(Paddle)
      s2_1(Transform)
    end

    subgraph ball_collision
      direction LR
      s3_0(Scoreboard)
      s3_1(Ball)
      s3_2(Brick)
      s3_3(Collider)
      s3_4(Transform)
      s3_5(Velocity)
    end

    subgraph scoreboard
      direction LR
      s4_0(Scoreboard)
      s4_1(Text)
    end

  end

  Systems<-->World

doup · 2022-05-29T14:58:07Z

I like what you're trying to do here, and I agree that it would be much better if these charts where defined in the markdown files… but, for me it looks ugly. (sorry 🙏) You could improve it with custom CSS for mermaid, but you probably won't have enough layout control.

For context, I did the chart in Figma, which allows to have shared components/styles, etc. It's relatively easy to maintain once you have access to the file and know the basics. Which, of course, are two important blockers for contribution/maintainability. But, it doesn't look that bad, if you question the following: Statically rendered images will quickly become outdated and are hard to maintain (unless some automated setup). Unless the breakout example or Bevy internals change substantially I think that chart will age quite. If the charts are in the correct abstraction level, not matching implementation details, should help in maintainability.

Anyway, maybe is a crazy idea, but what about creating the charts in plain HTML+CSS? If you know about flexbox/grid it should be doable… actually Figma and other design tools just copy the browser layout options. Responsive might be tricky though.

Weibye · 2022-05-29T15:52:16Z

for me it looks ugly.

I absolutely agree. Using mermaid out-of-the-box is not going to give us what we need. Both layout and theming limitations makes the diagram above rather useless as a visual aide.

I've been spending the day trying to see how far I can get within mermaid to achieve something more similar to what you created and this is as far as I have gotten atm.

This version is better, but IMO it is still not good enough. Mermaid as it currently stand does not (at this point) support the kind of layouting or color theming that we need to solve the Breakout diagram.

flowchart LR
  classDef resource fill:#148470,color:#fff
  classDef component fill:#feffcb,color:#535353
  style group0 fill:none,stroke:none
  style group1 fill:none,stroke:none
  style group2 fill:none,stroke:none
  style group3 fill:none,stroke:none

  style Entities fill:#fff2d9,stroke:#FFF,stroke-width:10px,opacity:0.4
  style Resources fill:#e6fbf6,stroke:#5ae0c0,stoke-width:20px,opacity:0.4

  style e1 fill:#c97
  style e2 fill:#c97
  style e3 fill:#c97
  style e4 fill:#c97
  style e5 fill:#c97
  style e6 fill:#c97
  style e7 fill:#c97
  style e8 fill:#c97
  style e9 fill:#c97
  style e10 fill:#c97

  style s0 fill:#61809e,stroke:#406287,stroke-width:5px
  style s1 fill:#61809e,stroke:#406287,stroke-width:5px
  style s2 fill:#61809e,stroke:#406287,stroke-width:5px
  style s3 fill:#61809e,stroke:#406287,stroke-width:5px
  style s4 fill:#61809e,stroke:#406287,stroke-width:5px

  subgraph World
    direction LR

    subgraph Resources
      direction TB
      r0(Input):::resource
      r1(AssetServer):::resource
      r2(Scoreboard):::resource

    end

    subgraph Entities
      direction LR

      subgraph group0[ ]
        direction TB
        subgraph e1[#1 Paddle]
          direction LR
          c1_0(Paddle):::component
          c1_1(Sprite):::component
          c1_2(Transform):::component
          c1_3(Collider):::component
        end
        subgraph e2[#2 Ball]
          direction LR
          c2_0(Ball):::component
          c2_1(Sprite):::component
          c2_2(Transform):::component
          c2_3(Velocity):::component
        end
        subgraph e3[#3 Score]
          direction LR
          c3_0(Text):::component
          c3_1(Style):::component
        end

        subgraph e4[#4 Top-Wall]
          direction LR
          c4_0(Sprite):::component
          c4_1(Transform):::component
          c4_2(Collider):::component
        end

        subgraph e5[#5 Right-Wall]
          direction LR
          c5_0(Sprite):::component
          c5_1(Transform):::component
          c5_2(Collider):::component
        end
      end

      subgraph group1[ ]
        direction TB
        subgraph e6[#6 Bottom-Wall]
          direction LR
          c6_0(Sprite):::component
          c6_1(Transform):::component
          c6_2(Collider):::component
        end

        subgraph e7[#7 Left-Wall]
          direction LR
          c7_0(Sprite):::component
          c7_1(Transform):::component
          c7_2(Collider):::component
        end

        subgraph e8[#8 Brick]
          direction LR
          c8_0(Brick):::component
          c8_1(Sprite):::component
          c8_2(Transform):::component
          c8_3(Collider):::component
        end

        subgraph e9[#9 Brick]
          direction LR
          c9_0(Brick):::component
          c9_1(Sprite):::component
          c9_2(Transform):::component
          c9_3(Collider):::component
        end

        subgraph e10[#...]
          direction LR
          c10_0(...):::component
        end
      end


    end
  end

  subgraph Systems
    direction TB

    subgraph group2[ ]
      direction LR
      subgraph s0[setup]
        direction LR
        s0_0(AssetServer):::resource
      end

      subgraph s1[paddle_movement]
        direction LR
        s2_0(Input):::resource
        s2_1(Paddle):::component
        s2_2(Transform):::component
      end

      subgraph s2[scoreboard]
        direction LR
        s4_0(Scoreboard):::resource
        s4_1(Text):::component
      end
    end

    subgraph group3[ ]
      direction LR
      subgraph s3[apply_velocty]
        direction LR
        s1_0(Transform):::component
        s1_1(Velocity):::component
      end

      subgraph s4[ball_collision]
        direction LR
        s3_0(Scoreboard):::resource
        s3_1(Ball):::component
        s3_2(Brick):::component
        s3_3(Collider):::component
        s3_4(Transform):::component
        s3_5(Velocity):::component
      end
    end
  end

  Systems-->World
  World-->Systems

Source code:

```

flowchart LR

    classDef resource fill:#148470,color:#fff
    classDef component fill:#feffcb,color:#535353
    style group0 fill:none,stroke:none
    style group1 fill:none,stroke:none
    style group2 fill:none,stroke:none
    style group3 fill:none,stroke:none

    style Entities fill:#fff2d9,stroke:#FFF,stroke-width:10px,opacity:0.4
    style Resources fill:#e6fbf6,stroke:#5ae0c0,stoke-width:20px,opacity:0.4

    style e1 fill:#c97
    style e2 fill:#c97
    style e3 fill:#c97
    style e4 fill:#c97
    style e5 fill:#c97
    style e6 fill:#c97
    style e7 fill:#c97
    style e8 fill:#c97
    style e9 fill:#c97
    style e10 fill:#c97

    style s0 fill:#61809e,stroke:#406287,stroke-width:5px
    style s1 fill:#61809e,stroke:#406287,stroke-width:5px
    style s2 fill:#61809e,stroke:#406287,stroke-width:5px
    style s3 fill:#61809e,stroke:#406287,stroke-width:5px
    style s4 fill:#61809e,stroke:#406287,stroke-width:5px

    subgraph World
        direction LR

        subgraph Resources
        direction TB
        r0(Input):::resource
        r1(AssetServer):::resource
        r2(Scoreboard):::resource

        end

        subgraph Entities
        direction LR

        subgraph group0[ ]
            direction TB
            subgraph e1[#1 Paddle]
            direction LR
            c1_0(Paddle):::component
            c1_1(Sprite):::component
            c1_2(Transform):::component
            c1_3(Collider):::component
            end
            subgraph e2[#2 Ball]
            direction LR
            c2_0(Ball):::component
            c2_1(Sprite):::component
            c2_2(Transform):::component
            c2_3(Velocity):::component
            end
            subgraph e3[#3 Score]
            direction LR
            c3_0(Text):::component
            c3_1(Style):::component
            end

            subgraph e4[#4 Top-Wall]
            direction LR
            c4_0(Sprite):::component
            c4_1(Transform):::component
            c4_2(Collider):::component
            end

            subgraph e5[#5 Right-Wall]
            direction LR
            c5_0(Sprite):::component
            c5_1(Transform):::component
            c5_2(Collider):::component
            end
        end

        subgraph group1[ ]
            direction TB
            subgraph e6[#6 Bottom-Wall]
            direction LR
            c6_0(Sprite):::component
            c6_1(Transform):::component
            c6_2(Collider):::component
            end

            subgraph e7[#7 Left-Wall]
            direction LR
            c7_0(Sprite):::component
            c7_1(Transform):::component
            c7_2(Collider):::component
            end

            subgraph e8[#8 Brick]
            direction LR
            c8_0(Brick):::component
            c8_1(Sprite):::component
            c8_2(Transform):::component
            c8_3(Collider):::component
            end

            subgraph e9[#9 Brick]
            direction LR
            c9_0(Brick):::component
            c9_1(Sprite):::component
            c9_2(Transform):::component
            c9_3(Collider):::component
            end

            subgraph e10[#...]
            direction LR
            c10_0(...):::component
            end
        end


        end
    end

    subgraph Systems
        direction TB

        subgraph group2[ ]
        direction LR
        subgraph s0[setup]
            direction LR
            s0_0(AssetServer):::resource
        end

        subgraph s1[paddle_movement]
            direction LR
            s2_0(Input):::resource
            s2_1(Paddle):::component
            s2_2(Transform):::component
        end

        subgraph s2[scoreboard]
            direction LR
            s4_0(Scoreboard):::resource
            s4_1(Text):::component
        end
        end

        subgraph group3[ ]
        direction LR
        subgraph s3[apply_velocty]
            direction LR
            s1_0(Transform):::component
            s1_1(Velocity):::component
        end

        subgraph s4[ball_collision]
            direction LR
            s3_0(Scoreboard):::resource
            s3_1(Ball):::component
            s3_2(Brick):::component
            s3_3(Collider):::component
            s3_4(Transform):::component
            s3_5(Velocity):::component
        end
        end
    end

    Systems-->World
    World-->Systems

  
</details>

Weibye · 2022-05-29T15:57:53Z

Anyway, maybe is a crazy idea, but what about creating the charts in plain HTML+CSS?

I'm going to give this an attempt next, it might just be simpler

Weibye · 2022-05-29T18:11:00Z

Anyway, maybe is a crazy idea, but what about creating the charts in plain HTML+CSS?

Based on some hours of investigation it seems that in order to display raw html in a page you need to create shortcodes. Which would mean creating a new shortcode for every unique diagram which in neither scalable nor useful.

A potential solution would be to create nested shortcodes where you would write a syntax similar to mermaid, defining graphs, subgraphs and nodes, but that is currently not yet supported in zola: getzola/zola#515

And that would not guarantee it would be possible to solve the layout part of the problem

alice-i-cecile · 2022-05-29T19:00:30Z

That's a shame. I'm going to close this out for now since this doesn't seem workable, but I'm hopeful that we can still get something better than "commit SVG files" out of #378.

Weibye added 2 commits May 29, 2022 10:23

Adding support for mermaid

da07d3f

eol

93c664c

DJMcNab reviewed May 29, 2022

View reviewed changes

Weibye added 2 commits May 29, 2022 11:46

Now using supplied mermaid instead of fetched one

8a0d473

Not blocking load on mermaid parse

ab1fb5f

Weibye mentioned this pull request May 29, 2022

Add a way to draw charts, graphs and diagrams from markdown / code / text #378

Open

alice-i-cecile closed this May 29, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add support for mermaid diagrams #377

Add support for mermaid diagrams #377

Uh oh!

Weibye commented May 29, 2022 •

edited

Loading

Uh oh!

DJMcNab May 29, 2022

Uh oh!

Weibye May 29, 2022

Uh oh!

Weibye May 29, 2022

Uh oh!

DJMcNab May 29, 2022

Uh oh!

Weibye May 29, 2022

Uh oh!

Weibye commented May 29, 2022

Uh oh!

doup commented May 29, 2022

Uh oh!

Weibye commented May 29, 2022

Uh oh!

Weibye commented May 29, 2022

Uh oh!

Weibye commented May 29, 2022

Uh oh!

alice-i-cecile commented May 29, 2022

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Add support for mermaid diagrams #377

Add support for mermaid diagrams #377

Uh oh!

Conversation

Weibye commented May 29, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

Usage

Feedback wanted

Uh oh!

DJMcNab May 29, 2022

Choose a reason for hiding this comment

Uh oh!

Weibye May 29, 2022

Choose a reason for hiding this comment

Uh oh!

Weibye May 29, 2022

Choose a reason for hiding this comment

Uh oh!

DJMcNab May 29, 2022

Choose a reason for hiding this comment

Uh oh!

Weibye May 29, 2022

Choose a reason for hiding this comment

Uh oh!

Weibye commented May 29, 2022

Uh oh!

doup commented May 29, 2022

Uh oh!

Weibye commented May 29, 2022

Uh oh!

Weibye commented May 29, 2022

Uh oh!

Weibye commented May 29, 2022

Uh oh!

alice-i-cecile commented May 29, 2022

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Weibye commented May 29, 2022 •

edited

Loading