Pre-render Mermaid Diagrams for Confluence Upload

[susannekoerber]

Is your feature request related to a problem? Please describe.
Mermaid diagrams in documentation do not render in Confluence Cloud because Content Security Policy (CSP) restrictions block client-side JavaScript execution. The current implementation relies on client-side JavaScript to render Mermaid diagrams, which fails in Confluence Cloud environments.

When publishing documentation to Confluence, Mermaid code blocks appear as plain text instead of rendered diagrams, making the documentation less useful and visually unappealing.

Describe the solution you'd like
ermaid diagrams in documentation do not render in Confluence Cloud because Content Security Policy (CSP) restrictions block client-side JavaScript execution. The current implementation relies on client-side JavaScript to render Mermaid diagrams, which fails in Confluence Cloud environments.

When publishing documentation to Confluence, Mermaid code blocks appear as plain text instead of rendered diagrams, making the documentation less useful and visually unappealing.

Describe the solution you'd like

Add a configuration option to pre-render Mermaid diagrams as images (SVG or PNG) before uploading to Confluence. This would:

1. Extract Mermaid code blocks from markdown during the Confluence generation process
2. Use mermaid-cli (or alternative renderers) to convert diagrams to static images
3. Upload the rendered images as attachments to Confluence
4. Replace the original code blocks with image references in the Confluence page content

Configuration example:

{
    "confluence": {
        "pre_render_mermaid": true,
        "mermaid_cli_path": "mmdc",
        "mermaid_image_format": "svg",
        "mermaid_image_width": 1024,
        "mermaid_image_height": 600
    }
}

Key features:

• Optional pre-rendering (disabled by default to maintain backward compatibility)
• Support for SVG (recommended) and PNG formats
• Configurable image dimensions
• Flexible renderer selection (mermaid-cli, npx, or custom path)
• Graceful fallback to original client-side rendering if pre-rendering fails

Describe alternatives you've considered

1. Manual conversion: Manually converting Mermaid diagrams to images before adding them to documentation - too time-consuming and error-prone
2. Confluence HTML macro: Using Confluence's HTML macro with embedded JavaScript - blocked by CSP in Confluence Cloud
3. External hosting: Hosting rendered images externally and linking to them - adds complexity and external dependencies
4. Confluence plugins: Using third-party Confluence plugins - requires additional setup and may not be available in all Confluence instances

Pre-rendering during the Daux generation process is the most reliable and maintainable solution.

Additional context

Implementation approach:

• Uses an abstraction layer (interface + factory pattern) to allow for multiple renderer implementations
• Currently implements mermaid-cli renderer with architecture ready for future Node.js or Kroki-based renderers
• Integrates seamlessly with existing Confluence upload process
• Maintains backward compatibility (feature is opt-in via configuration)

Prerequisites:

• Requires @mermaid-js/mermaid-cli to be installed (or accessible via npx)
• Works with both Confluence Cloud and Confluence Server/Data Center

Benefits:

• Reliable diagram rendering regardless of Confluence CSP settings
• Better performance (no client-side rendering needed)
• Consistent diagram appearance across all Confluence instances
• No additional Confluence plugins required