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

[Weibye]

Motivation

• A lot of the learning-material in the Bevy-book can be improved by displaying graphs or diagrams as shown here: [Merged by Bors] - Introduction for ECS chapter #290 (comment)
• Nearly all release-notes contain some form of charts, and will likely continue to do so in the future. Improving the process of creating these charts could take workload off of core maintainers and democratize the process
• Hypothesis: Graphs and diagrams that are drawn from text or code is easier to maintain by a team compared to static images generated by a user
• I initially thought adding mermaid support would be enough (Add support for mermaid diagrams #377) but after playing with it some it seems to not fully suitable
  • See the following comment-chain for details: Add support for mermaid diagrams #377 (comment)
  • TLDR; mermaid is not really set up for ease of customization

Types of diagrams we should consider supporting

I've focused on diagrams already in use or known to wanted in the near future

Type	Examples	Notes
Gantt Diagram	1	This example isn't enough to warrant spending tons of resources supporting this type of diagram. This is more "icon" than "diagram"
Flowchart	1	Same as above
Bar Chart	1 2 3 4 5 6 7 8 9	Due to its already extensive usage, supporting this makes sense
"ECS Overview Diagram"	1	This type of diagram would be extremely useful to display at the start of every example

Potential Solutions

mermaid

What

Javascript framework for rendering various diagrams

Pros

• Very easy to create charts and diagrams
  • as long as they are the types of diagrams defined by mermaid
• Proven to work with Zola (Add support for mermaid diagrams #377)

Cons

• Hard to customize beyond colors and outlines
• Poor layout solver with virtually no control, leading to unreadable diagrams as they grow in size
  • Some types of diagrams are better than others

HTML + CSS

What

By using shortcodes in Zola it is possible to create html blocs and display them in a page. However, for that to be composable and useful, we would need to add support for nested shortcodes, in which case we could write shortcodes somewhat similar to a mermaid script.

(Are there other ways to get it working?)

Pros

• No javascript or external dependencies needed

Cons

• Requires implementing support for nested shortcodes in Zola (something that the maintainer says is very unlikely to happen Allow shortcodes in shortcode bodies getzola/zola#515)

LaTeX

What

LaTeX is a high-quality typesetting system; it includes features designed for the production of technical and scientific documentation.

Example of how it looks in use

Pros

• LaTeX is very powerful

Cons

• Most likely requires getting a plugin-system to work in Zola
• Can LaTeX solve these various diagrams without adding too much overhead or maintenance concerns?

Feedback wanted

• Is this something that is valuable to pursue?
• Would solving this improve our current or future situation?
• Are there other types of diagrams we should consider adding to the list above?
• Are there other technologies or approaches that could solve this?

[alice-i-cecile]

I wonder if we can automatically generate something "ECS overview diagrams" as part of a Bevy editor, and then include screenshots of that through a build system 🤔 Really, these seem like a generally-useful bit of tech, rather than specific to this book.

[connorgmeehan]

I am looking into this again, and had a little discussion in the documentation-dev channel with a few others. I had a crack at implementing the diagrams with a few approaches: handcoding svgs, shortcode generated svgs, external assets and mermaid diagrams. Any interest in discussing further in the thread @alice-i-cecile @Weibye?

[alice-i-cecile]

I don't have a ton of bandwidth for this currently, but this is definitely functionality that I would like!