Render Mermaid diagrams referenced from a .mmd or .mermaid file

[sumau]

🏷️ Discussion Type

Product Feedback

💬 Feature/Topic Area

Code Search and Navigation

Body

Feature request

Render Mermaid diagrams referenced from a .mmd or .mermaid file — both same-repo relative paths and
cross-repo raw URLs — the way SVG images work today:

![Payment flow](./docs/diagrams/payment-flow.mmd)
![Shared architecture](https://raw.githubusercontent.com/my-org/platform-docs/main/diagrams/architecture.mmd)

What GitHub already supports

GitHub currently renders Mermaid in two places:

1. Inline fenced blocks in Markdown files, issues, PRs, discussions, and wikis
   (docs):

   graph LR
     A --> B
   

   Loading

2. Standalone .mermaid / .mmd files viewed directly in blob view
   (docs).

The missing piece

There is no way to reference a .mmd file from a Markdown file, the way image
paths work today. ![](./diagram.svg) renders inline; ![](./diagram.mmd) does not —
and neither does a raw URL to a .mmd file in another repository, even though the
equivalent raw SVG URL renders fine.

This means a diagram has no single source of truth:

• The same diagram needed in several files (root README, docs pages, sub-package READMEs)
  must be copy-pasted as fenced blocks, which inevitably drift apart.
• Organizations with a canonical architecture diagram cannot reference it from each
  service's repository — the exact use case in Is it possible to reference another diagram within a diagram / magic cross linking? mermaid-js/mermaid#1944, open since 2021.
  The upstream Mermaid project cannot fix this, because rendering is the host's job.
• The practical workaround today is a CI compile step: pre-render every diagram to SVG
  with mermaid-cli and commit the images (e.g. feat: add --keep-source to retain mermaid source in Markdown output mermaid-js/mermaid-cli#1114,
  https://github.com/nielsvaneck/render-md-mermaid). This works — and the SVG can then
  be referenced cross-repo via its raw URL — but it duplicates every diagram as a build
  artifact and goes stale the moment someone edits the source without re-rendering.
• Encoding the source into a mermaid.ink / Mermaid Live URL avoids the build step but
  moves the diagram out of the repo into an unreadable base64 blob in the URL.

Proposed behavior

When the target of Markdown image syntax is a .mmd / .mermaid file, render it as a
Mermaid diagram (in the same sandboxed viewer used for fenced blocks and blob view),
with exactly the same resolution and access semantics as images:

1. Relative path, same repo — resolved at the same ref as the Markdown file being
   rendered, subject to the same access control:

   ![Payment flow](./docs/diagrams/payment-flow.mmd)

2. Absolute raw URL, any repo — fetched the way raw image URLs are fetched today
   (anonymously, via GitHub's proxy). This works for public repositories and fails for
   private ones — identical to the behavior of a cross-repo raw SVG URL now, so it
   introduces no new permission surface:

   ![Shared architecture](https://raw.githubusercontent.com/my-org/platform-docs/main/diagrams/architecture.mmd)

   Pinning to a tag or commit SHA instead of a branch gives stable embeds, again exactly
   as with images.

Because both forms reuse the existing image-resolution rules and the existing sandboxed
Mermaid renderer, this avoids the cross-origin, permission, and cache-invalidation
questions that general Markdown transclusion would raise: nothing becomes fetchable that
isn't fetchable today, and staleness behaves no differently than a referenced image.

Who benefits

• Organizations keeping canonical system diagrams in one docs repo, referenced from every
  service repo (Is it possible to reference another diagram within a diagram / magic cross linking? mermaid-js/mermaid#1944).
• Monorepos where sub-package READMEs share system diagrams.
• Teams whose non-technical members edit diagrams: one .mmd file is the diagram,
  editable in blob view, rendered everywhere it's referenced — across repositories.

[github-actions[bot]]

💬 Your Product Feedback Has Been Submitted 🎉

Thank you for taking the time to share your insights with us! Your feedback is invaluable as we build a better GitHub experience for all our users.

Here's what you can expect moving forward ⏩

• Your input will be carefully reviewed and cataloged by members of our product teams. 
  • Due to the high volume of submissions, we may not always be able to provide individual responses.
  • Rest assured, your feedback will help chart our course for product improvements.
• Other users may engage with your post, sharing their own perspectives or experiences. 
• GitHub staff may reach out for further clarification or insight. 
  • We may 'Answer' your discussion if there is a current solution, workaround, or roadmap/changelog post related to the feedback.

Where to look to see what's shipping 👀

• Read the Changelog for real-time updates on the latest GitHub features, enhancements, and calls for feedback.
• Explore our Product Roadmap, which details upcoming major releases and initiatives.

What you can do in the meantime 💻

• Upvote and comment on other user feedback Discussions that resonate with you.
• Add more information at any point! Useful details include: use cases, relevant labels, desired outcomes, and any accompanying screenshots.

As a member of the GitHub community, your participation is essential. While we can't promise that every suggestion will be implemented, we want to emphasize that your feedback is instrumental in guiding our decisions and priorities.

Thank you once again for your contribution to making GitHub even better! We're grateful for your ongoing support and collaboration in shaping the future of our platform. ⭐

[AhmadHassan-BTed]

This would be a massive quality-of-life upgrade for docs : ( But, currently and Sadly, you're forced to choose between pre-rendering SVGs via CI (which gets stale fast) or using those messy base64 blobs with Mermaid Live. Neither is a real "source of truth." Definitely push this through the official GitHub feedback form; discussions are great for visibility, but that's how this actually gets on the engineering roadmap.

[sumau]

Thanks for the vote of confidence :-) Which official GitHub feedback form are you referring to by the way? There's no mention of this in the docs: https://docs.github.com/en/support/sharing-feedback-with-github

[AhmadHassan-BTed]

There's this way, that; If you want to make this proposal way more viable for their engineering team, don't just ask for a renderer. Pitch it as a "Canonical Diagram Reference" system. Right now, if you just ask for "rendering," they’ll worry about the security nightmare of cross-repo fetches.

Instead, suggest they implement a specific mermaid tag that uses the same exact proxy logic they already use for images. Because they already have a secure, sandboxed path for fetching and rendering raw blobs, this isn't a new feature; it's just extending the existing image-processing pipeline to the Mermaid viewer. That makes it a "low-hanging fruit" task for them rather than a huge architectural change.

[sumau]

As an alternative I've also raised https://github.com/orgs/mermaid-js/discussions/7966 to embed the Mermaid code within the generated SVG with Mermaid :-)