Support C4 Model diagram syntax in Mermaid renderer

[magnus919]

Summary

GitHub's built-in Mermaid renderer does not support the C4 diagram extension (@mermaid-js/mermaid), which means C4 Model diagrams cannot be rendered inline in issues, pull requests, discussions, or markdown files despite being an industry standard for software architecture documentation.

Problem

The C4 Model (Context, Container, Component, Code) by Simon Brown is the most widely adopted standard for software architecture diagramming. The Mermaid project has a first-party C4 plugin that extends Mermaid syntax with domain-specific types: C4Context, C4Container, C4Component, along with supporting directives like Person(), System(), System_Ext(), Container_Boundary(), Rel(), and Db().

Currently, code blocks like:

C4Context
    title System Context diagram
    Person(user, User)
    System(sys, System)
    Rel(user, sys, Uses)

render as raw text on GitHub instead of as diagrams, because GitHub's bundled Mermaid does not include the C4 extension.

Impact

• Architecture Decision Records (ADRs) that reference C4 diagrams cannot embed them natively
• PR descriptions explaining architectural changes require external image hosting
• Issue discussions about system design lack inline architecture context
• Teams using ADRs, C4, arc42, or similar documentation standards must maintain separate diagram hosting

Requested Change

Bundle the @mermaid-js/mermaid C4 extension into GitHub's Mermaid rendering pipeline, matching the support already available in Atlassian's Mermaid implementation (Bitbucket/Confluence).

Prior Art

• The C4 Mermaid extension is actively maintained at @mermaid-js/mermaid (npm)
• Atlassian already supports C4 syntax in their Mermaid renderer
• The C4 model is the de facto standard for software architecture diagrams
• Mermaid is already bundled by GitHub; this is adding an existing plugin, not building new rendering infrastructure

Workaround

Teams currently export C4 diagrams as PNG/SVG and host them separately, or use GitHub-compatible flowchart syntax with subgraphs. Neither preserves the semantic meaning of C4 boundary types, and external image hosting breaks the diagrams-as-code advantage.

[github-actions[bot]]

Thank you for your interest in contributing to our community! We currently only accept discussions created through the GitHub UI using our provided discussion templates. Please re-submit your discussion by navigating to the appropriate category and using the template provided.

This discussion has been closed because it was not submitted through the expected format. If you believe this was a mistake, please reach out to the maintainers.