enable elk renderer for embedded mermaid charts

[moui72]

Select Topic Area

Question

Body

Any chance we can get support for the elk layout engine for mermaid charts?

https://github.com/mermaid-js/mermaid/tree/develop/packages/mermaid-layout-elk

With a complex chart, it looks pretty confusing with the default renderer

flowchart
 subgraph api-demographics["api-demographics"]
        D[("Database")]
        ABC["some-service<br><small><em>ABC on DEF</em></small>"]
        R[["Dying Service<br><small><em>Deprecated Soon</em></small>"]]
        W["Another Service"]
  end
  subgraph something
        F["something"]
        L[("Destination")] 
  end
    P[["Source"]]
    E["something-else<br><small><em>Deprecated Eventually</em></small>"]
    F["even-more-things<br><small><em>Dependency Eliminated Eventually</em></small>"]
    G["whatever"]
    H["another thing"]
    J{{"Secrets"}}
    K[("Potato")]
    ABC -.-> R -.-> D
    ABC -.-> F & E
    ABC == Build time dependency ==> J
    ABC --> D & L & Fa & G & H
    P --> W
    W --> D & L & Fa & J & K
    style R stroke:#666,fill:#EEE
    style F stroke:#660,fill:#FFC
    style E stroke:#660,fill:#FFC
    style W stroke:blue,fill:#CCF
    style ABC stroke: green, fill: #CFC
    linkStyle default stroke:green
    linkStyle 10,11,12,13,14,15 stroke:blue,color:blue

Loading

You can see it's rendered the same on GH at the time of writing this, even if I try to switch the renderer via the using flowchart-elk chart type, because github has not installed @mermaid-js/layout-elk

flowchart-elk
 subgraph api-demographics["api-demographics"]
        D[("Database")]
        ABC["some-service<br><small><em>ABC on DEF</em></small>"]
        R[["Dying Service<br><small><em>Deprecated Soon</em></small>"]]
        W["Another Service"]
  end
  subgraph something
        F["something"]
        L[("Destination")] 
  end
    P[["Source"]]
    E["something-else<br><small><em>Deprecated Eventually</em></small>"]
    F["even-more-things<br><small><em>Dependency Eliminated Eventually</em></small>"]
    G["whatever"]
    H["another thing"]
    J{{"Secrets"}}
    K[("Potato")]
    ABC -.-> R -.-> D
    ABC -.-> F & E
    ABC == Build time dependency ==> J
    ABC --> D & L & Fa & G & H
    P --> W
    W --> D & L & Fa & J & K
    style R stroke:#666,fill:#EEE
    style F stroke:#660,fill:#FFC
    style E stroke:#660,fill:#FFC
    style W stroke:blue,fill:#CCF
    style ABC stroke: green, fill: #CFC
    linkStyle default stroke:green
    linkStyle 10,11,12,13,14,15 stroke:blue,color:blue

Loading

Here's what it looks like when I render it using elk on www.mermaidchart.com

[kpietraszko]

I'm surprised this isn't supported. ELK is often much more readable, not just in complex nested diagrams and edge-cases.

[ferdef]

Any chance this is going to be added? It's confusing that ELK is supported from the Visual Studio Mermaid plugin, but once you push the changes the diagram looks completely different in Github

[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. ⭐

[whinee]

oh man, an auto-response from github bot just came a week ago, while the feature request was made in checks notes Sep 12, 2024??? sadge :(

[MessiasLima]

Any update?

[cgulotta]

Also interested in using this layout for our project; have a very large flowchart that looks way better with elk rendering

[aarush0101]

Hey there,

Looks like it's been a year without responses from any of the staff. You could try opening a feature request by tagging then on Twitter, risky but works, since I see no real workaround. Hope they notice you. Good luck!

[MessiasLima]

Guys, I posted on X

https://x.com/AppOutletTeam/status/1942254916099031190

Could you please help me to make some noise there?

[aarush0101]

Guys, I posted on X

https://x.com/AppOutletTeam/status/1942254916099031190

Could you please help me to make some noise there?

Reposted

[ryan-padilla-tph]

Also reposted

[whinee]

reposted! lets make more noise! frfr

[sachinthack]

waiting on this

[deryann]

+1

[gsauvage]

Same here, it would be awesome to have this for our charts !

[JohnYoungers]

This seems like an easy win: I'm not sure if there's a reason not to add it.

And on a minor side-track, if we could give the expand view a little TLC as well, that would be great; we use this to render our database schemas as erDiagrams, and the expanded view with zooming in/out is not the most ideal UX it could be

[OrionSehn]

bumping this, would be appreciated

[ilanthendral]

+1
Waiting on this, increase readability and value of diagrams by minimum of 10x

[gregormelhorn]

+1 push

[gregormelhorn]

This is my temporary workaround since I am really annoyed by status quo. You can feed this into your AI tool to get a working solution:

Instructions: Implementing Mermaid ELK → SVG Auto-Rendering Hook

  Goal: Create a pre-commit hook that automatically converts complex ELK-layout Mermaid diagrams to external SVG files while leaving simple diagrams as raw Mermaid.

  Requirements

  Core Behavior:
  - Only process Mermaid diagrams with layout: elk in their config
  - Leave non-ELK diagrams (sequence, gantt, etc.) as raw Mermaid blocks
  - Generate hash-based SVG filenames for stability (MD5 of Mermaid source)
  - Store SVGs in ./diagrams/ subdirectory relative to each markdown file
  - Preserve original Mermaid source in collapsible <details> blocks
  - Track hash in data-diagram-hash attribute for fast comparison
  - Auto-stage all changes (SVGs + markdown) to continue commit seamlessly
  - Implement garbage collection to remove unused SVG files

  Implementation Steps

  1. Create Main Processing Script

  File: .git-hooks/process-diagrams.js

  Core Functions Needed:
  // Get staged markdown files from git
  function getStagedMarkdownFiles()

  // Generate MD5 hash of diagram code
  function hashDiagram(code)

  // Check if diagram uses ELK layout (regex: /layout:\s*elk/)
  function usesElkLayout(code)

  // Validate Mermaid syntax before rendering
  function validateMermaidSyntax(code, filePath)

  // Render Mermaid to SVG using npx @mermaid-js/mermaid-cli
  function renderMermaidToSVG(code, outputPath)

  // Get diagram directory for markdown file (dirname + "/diagrams")
  function getDiagramDir(mdFile)

  // Ensure diagram directory exists
  function ensureDiagramDir(mdFile)

  // Track referenced SVGs per directory for garbage collection
  function trackReferencedSvg(diagramDir, svgName)

  // Process a single markdown file
  function processFile(mdFile)

  // Garbage collection: delete unused SVGs
  function cleanupUnused()

  Processing Logic:
  1. Get all staged markdown files from git diff --cached --name-only --diff-filter=ACM
  2. For each markdown file:
    - Create ./diagrams/ subdirectory if needed
    - Find all patterns (using regex):
      - Pattern A: Already processed with ![Diagram] + <details data-diagram-hash="...">
      - Pattern B: Raw ````mermaid` blocks (new diagrams)
  3. For Pattern A (already processed):
    - Extract hash from data-diagram-hash attribute
    - Extract Mermaid code from <details> block
    - Calculate new hash from code
    - Check if ELK diagram:
        - If not ELK: convert back to raw Mermaid
      - If ELK: check if hash changed OR path wrong OR file missing
            - If needs update: validate, render SVG, update markdown
        - Track SVG reference
  4. For Pattern B (raw Mermaid):
    - Skip if inside <details> block (already processed)
    - Skip if inside ````markdown` code block (examples)
    - Check if uses ELK layout:
        - If not ELK: skip (leave as raw Mermaid)
      - If ELK: validate, render SVG, replace with ![Diagram] + <details> format
      - Track SVG reference
  5. Apply all replacements to file content
  6. If changed: write file, stage with git add
  7. Run garbage collection on each diagram directory

  Regex Patterns:
  // Already processed with ![Diagram]
  /!\[Diagram\]\(([^)]+\/([a-f0-9]+)\.svg)\)\s*\n\s*<details data-diagram-hash="([a-f0-9]+)">\s*<summary>Original Mermaid Diagram \(for AI\)<\/summary>\s*\n\s*```mermaid\s*([\s\S]*?)```\s*\n\s*<\/details>/gm

  // Raw Mermaid blocks
  /```mermaid[\w-]*\s*([\s\S]*?)```/gm

  Output Format (for ELK diagrams):
  ![Diagram](./diagrams/abc123hash.svg)

  <details data-diagram-hash="abc123hash">
  <summary>Original Mermaid Diagram (for AI)</summary>

  ```mermaid
  ---
  config:
    layout: elk
  ---
  flowchart TB
      A --> B

  Skip Conditions:
  - Mermaid block preceded by "Original Mermaid Diagram" without closing </details>
  - Mermaid block followed immediately by </details>
  - Mermaid block inside markdown` or html` code blocks

  Garbage Collection:
  - Track all SVG references per directory in a Map
  - For each diagram directory:
    - List all .svg files
    - Delete files not in reference set
    - Stage directory with git add

  2. Integrate with Pre-Commit

  File: .pre-commit-config.yaml

  Add hook before mermaid-syntax-check:
  - repo: local
    hooks:
      - id: mermaid-to-svg
        name: Render Mermaid diagrams to SVG
        entry: .git-hooks/process-diagrams.js
        language: system
        types: [markdown]
        files: \.md$
        exclude: ^(frontend/node_modules|api/venv|\.git)/
        pass_filenames: false

  3. Update Markdown Link Check Config

  File: .markdown-link-check.json

  Add pattern to ignore SVG links:
  {
    "ignorePatterns": [
      { "pattern": "^\\./diagrams/.*\\.svg$" }
    ]
  }

  4. Validation Integration

  Reuse existing check-mermaid-syntax.py for syntax validation:
  - Write Mermaid to temp file
  - Call python3 .git-hooks/check-mermaid-syntax.py "${tmpFile}"
  - If fails: skip diagram, log error
  - If succeeds: proceed with SVG generation

  5. SVG Generation Command

  Use npx to auto-install and run mermaid-cli:
  npx -y @mermaid-js/mermaid-cli@latest -i "${tmpFile}" -o "${outputPath}"

  Error Handling:
  - Catch rendering errors
  - Skip diagram if fails
  - Log clear error message
  - Don't block commit for other diagrams

  6. Testing Requirements

  Test Cases:
  1. Raw ELK diagram → should convert to SVG
  2. Raw non-ELK diagram → should leave as-is
  3. Already processed ELK diagram with hash match → no change
  4. Already processed ELK diagram with hash mismatch → regenerate
  5. Already processed with wrong path → fix path
  6. Missing SVG file → regenerate
  7. Mermaid in code block example → skip
  8. Non-ELK changed to ELK → convert to SVG
  9. ELK changed to non-ELK → convert back to raw Mermaid
  10. Unused SVG files → delete

  Success Criteria

  - ELK diagrams automatically converted to SVG on commit
  - Non-ELK diagrams unchanged (raw Mermaid)
  - Hash tracking enables fast comparison
  - Missing files regenerated automatically
  - Unused files cleaned up
  - All changes auto-staged
  - Commit proceeds without manual intervention
  - LLMs can edit Mermaid source in <details> blocks

  Dependencies

  - Node.js (for running script)
  - npx (for @mermaid-js/mermaid-cli, auto-installed)
  - Python 3 (for syntax validation)
  - Git (for staging operations)

  Documentation

  Create guide at docs/code-quality/mermaid-to-svg-guide.md explaining:
  - How the system works
  - When to use ELK layout vs raw Mermaid
  - How to edit diagrams (for humans and LLMs)
  - Directory structure
  - Troubleshooting common issues

[jsalsman]

It would be great for GitHub to enable the ELK renderer in markdown embedded Mermaid. There are no situations I can imagine where ELK would not be superior to the default renderer (see below for how terrible the default can be.)

To help get visibility for this request, here are public profiles for the Microsoft executives who influence developer-tools decisions including GitHub. Please share your use case engaging with one or all of them:

Scott Guthrie (EVP, Cloud + AI)
Twitter: https://twitter.com/scottgu
LinkedIn: https://www.linkedin.com/in/scottgu

Julia Liuson (President, Developer Division)
LinkedIn: https://www.linkedin.com/in/julia-liuson

Jay Parikh (EVP, CoreAI; GitHub reports under this group)
Twitter: https://twitter.com/jayparikh
LinkedIn: https://www.linkedin.com/in/jayparikh

If GitHub were to enable ELK by default or allow it as a selectable Mermaid config, users could produce cleaner, more maintainable diagrams directly in Markdown. Anyone else who wants this, please reach out to those three executives; showing them the concrete benefits is key to moving this forward.

(This is what we have to suffer without ELK:)

[szalapski]

Yes, please support a good ELK rendering of mermaid diagrams.

[Quiet27]

I would also like to see ELK rendering for mermaid diagrams.