content.mermaid_image plugin

[traut]

Background

Users can add Mermaid diagrams to the documents using content.text with format_as set to code and code_language set to mermaid, but in the case user's Markdown renderer does not support Mermaid diagrams, fabric should support static rendering.

Design

The plugin draws Mermaid diagrams as static images.

Specification

• No configuration options:
• API interface:
  • code -- a required string attribute that contains a Mermaid code.
  • alt_text -- an optional string attribute with alt text for the image tag
  • output_file -- a required string attribute that contains a path for the output file

Behaviour

The plugin renders mermaid diagram code into a static image and returns a Markdown image tag (similar to content.image).

The code value is treated as Go template string (query_result object from the local context)

For example,

content mermaid_image "foo" {
    code =  <<-EOT
      graph TD;
        A-->B;
        A-->C;
        B-->D;
        C-->D;
    EOT

    output_file = "/tmp/diagram.png"
    alt_text = "Mermaid diagram"
}

renders image

into /tmp/diagram.png and returns

![<alt_text>](<output_file>)

Important

Things to consider:

• Mermaid code can be rendered with
  • mermaid-cli (mmdc)
  • CDP-based (Chrome DevTools Protocol) library used to drive a headless browser on the system for rendering the diagrams (for example, mermaid.go)
• both approaches add an external requirement for the plugin -- either the external tool or the Chrome browser must be installed on the system where fabric runs
• mermaid-cli provides a convenient way of converting all mermaid code tags into images during post-processing of the Markdown file -- https://github.com/mermaid-js/mermaid-cli?tab=readme-ov-file#transform-a-markdown-file-with-mermaid-diagrams -- which lowers the need for this Fabric plugin.

Deliverables

• the new content.mermaid_image plugin
• the unit tests for the plugin

[traut]

This is a low-priority plugin since it depends on external tools and supplements an existing way of using Mermaid diagrams.

[dobarx]

I think this plugin is duplicate of content text. We can use:

content text {
   format_as = "code"
   code_language = "mermaid"
   text =  <<-EOT
      graph TD;
        A-->B;
        A-->C;
        B-->D;
        C-->D;
    EOT
}

And leave image rendering for markdown viewer. Since this will produce:

'''mermaid
graph TD;
   A-->A;
   A-->C;
   B-->D;
   C-->D;
'''

Resulting in viewers that support mermaid code blocks rendering image instead (e.g: Github):

graph TD;
   A-->A;
   A-->C;
   B-->D;
   C-->D;

Loading

[traut]

@dobarx indeed, it provides similar functionality, but, as noted in the "Background", it might be beneficial to have a static image generator. See also "Important" block with a couple of notes.

I suggest we leave this issue in draft state for now, to be revisited in the future

[dobarx]

Hmm, then there could be two approaches:

1. If we use goldmark go library with mermaid extension I see from docs we render differently based on output:
   • Render .md output just with codeblocks
   • Render .html output with client-side rendering (JS renders when browser opens)
   • Render .pdf output with server-side image rendering (requires Chrome or mermaid CLI as dependencies)
2. Drop mermaid as recommended diagram language and use D2 which is implemented in Go and will render images for all outputs without any external dependencies. Also plugs just as simple goldmark library extension.