Our documentation in InScope does not natively render Mermaid diagrams from our Markdown files. When developers check in diagram-as-code using Mermaid syntax (e.g., ```mermaid), it appears as a plain text block rather than a visual diagram.

We've been adopting a "diagrams as code" methodology to keep technical diagrams version-controlled and easy to update. While platforms like GitLab and GitHub render these diagrams automatically, our primary documentation tool, InScope, lacks this capability.

The current workaround is to manually generate the diagram, take a screenshot, and embed the static image into the Markdown file. This process is cumbersome and defeats the purpose of using Mermaid, as it creates a disconnect between the source code and the rendered documentation. We need a more integrated and automated solution.

Maybe relevant discussion: https://redhat-internal.slack.com/archives/C081A0ZLRDK/p1755008555625699

Done

• Identify if InScope has a native feature, plugin, or configuration that can be enabled to support Mermaid.js.
• If a native solution is unavailable, research third-party tools or CI/CD pipeline steps that can automate the conversion of Mermaid code blocks to images (e.g., SVG/PNG) as part of our workflow.  We do something similar with plantUML diagrams in our main github repo
• Document the pros, cons, relative effort, and potential costs of at least two viable solutions.
• Conclude with a clear recommendation on the best path forward.