mermaid directive

[Mpdreamz]

Mermaid

Kind	Link
Reference	https://mystmd.org/guide/directives#directive-mermaid
Documentation	https://mystmd.org/guide/diagrams

Implementation

• Parses directives and aliases
• Emits HTML
• Unit tests
• Validation (emits, warnings and errors).

Specification compliance:

• Body (string, required)
• Options
  • label, name (string) - Label the mermaid to be cross-referenced or explicitly linked to.

[theletterf]

I strongly support this proposal. I implemented Mermaid diagrams for docs-as-code in the past, and they're the solution to:

• Versioning and authoring diagrams.
• Avoid the variety of diagramming formats in the wild (I counted three so far).

Let me know if you need any help with this.

+CC @alaudazzi @bmorelli25

[Mpdreamz]

We initially had support for mermaid but decided to rip it out. I think we are all now in favor of including this back in.

cursorful-video-1744299611397.mp4

I spent a little time today adding it back in in this branch: https://github.com/elastic/docs-builder/tree/feature/mermaid-support

• Styling is a PITA, will take a full day to go over.
• Mermaid ESM module does not play nice with parcel. I hack included it but we get a gazillion bundle files in _static need to pair with @reakaleek and @cotti

Since this exceeded my timebox of 30minutes we will need to look into supporting this post 9.0.

[theletterf]

Re: Styling, couldn't we use the bundled styles? (Not the default one, the monochromatic ones for light and dark themes.)

[Mpdreamz]

Yes no, even changing the fonts is a bit tedious (but solved on that branch)

At a minimum the colors should inherit from our theme. A day might have been an exaggeration :).