Mermaid diagram rendering in Markdown preview

[szabba]

Check for existing issues

• [X] Completed

Describe the feature

Markdown is great for writing technical documentation maintained alongside the code, using the same workflows - but technical documentation often needs to contain diagrams.

Mermaid is a code-driven tool for preparing technical diagrams. It supports different types of diagrams, with different syntaxes.

GitLab and GitHub support rendering mermaid diagrams from fenced code blocks annotated as Mermaid code. VS Code code has plugins [^1] that enable viewing them in the Markdown preview. Notion.so supports something similar, though it's only Markdown-adjacent.

[^1]: I'm linking to the one with most installs as of submission.

If applicable, add mockups / screenshots to help present your vision of the feature

Here I've overlayed how GitHub renders these ono Zed:

Here's a screenshot showing how Notion lets the user switch betwen the code vs diagram view.

This might be nice to have for Zed. It is more important in Notion's use case. They don't have a strict separation between viewing and editing. In Zed that separation is the Markdown text buffer vs preview pane distinction.

[Spoutnik97]

@JosephTLyons is it still possible to develop this extension ? Does it depend on architectural stuff ? I could try to develop it

[ckmjreynolds]

+1

The only thing that keeps me using VSCode vs. Zed is the inability to properly edit README.md files for GitHub. In my case, the most glaring omission is the inability to include Mermaid diagrams.

[ckmjreynolds]

FWIW, I discovered it is possible to use Marked 2 (on MacOS) and use a simple preprocessor script to get Mermaid working in a preview with Zed. Not ideal, but maybe enough to allow me to stop using VSCode.

[Spoutnik97]

@ckmjreynolds how do you use the preprocessor ?

[ckmjreynolds]

@Spoutnik97

cat marked_preprocessor.sh
#!/bin/bash
cat ~/bin/head.html -

cat head.html
<script src="https://unpkg.com/mermaid@10/dist/mermaid.min.js"></script>
<script>
	mermaid.initialize({ startOnLoad: true });
	mermaid.initialize({ startOnLoad: true });
	Marked.hooks.register('update', function() { mermaid.run(); });
</script>

For some reason calling initialize twice is needed at least in my testing, you can instead do Cmd + R to refresh.

I pieced this together based on support information for both using Mermaid and using a preprocessor on Marked 2's support website.

[manchicken]

I just found that if you stick that Mermaid HTML at the top of your Markdown doc that it works in Marked2 right now.

I'd love to get this working in the in-editor preview, but I'll take this!

[manchicken]

Ok, here's the full Mermaid preprocessor. I didn't need to run init twice, and I updated the version of mermaid to track latest:

#!/bin/sh

echo '<script src="https://unpkg.com/mermaid@latest/dist/mermaid.min.js"></script> <script> mermaid.initialize({ startOnLoad: true }); Marked.hooks.register('update', function() { mermaid.run(); }); </script>'
while read line
do
  echo "$line"
done < "${1:-/dev/stdin}"

This should just be a drop-in replacement, and now you can set this in Marked:

[syepes]

@manchicken How is this configured in Zed, the screenshot is not from Zed. How are you previewing this mermaid in the markdown?

[manchicken]

@manchicken How is this configured in Zed, the screenshot is not from Zed. How are you previewing this mermaid in the markdown?

Someone said to use marked2, that's what the screenshot is from.

[baggiponte]

Would double down as a +1 for this feature for the AI Chat too!

[V-Legendre]

Any updates on this? Wanting this feature badly in August 2025 🙂

[tiptenbrink]

I think if Zed starts trying to support things like this themselves, there will be a never-ending stream of custom rendering features requested, until one day Markdown rendering will basically require implementing an entire browser. See also #30264. Some of them might be useful, but I suggest instead allowing extensions to provide custom rendering support. Providing some way for extensions to provide custom rendering might even allow proof assistants like Lean or Rocq/Coq to be used with Zed, which would be amazing.

[buzzvolt]

Hi,

I think it would be great to have a native support in the editor to render mermaid diagrams. they are most common these days.

[buzzvolt]

hi

I think there is a repetitive mention of a need for mermaid rendering in markdown preview in zed editor across issues/discussions. I would vote for having such functionality into zed, if that does not beef up zed code base by much and does not cause any resource leaks etc. there are at-least 171 upvotes to this, so I think that is good enough to consider this in the higher scheme of priorities.

[milahu]

I suggest instead allowing extensions to provide custom rendering support

https://github.com/zed-industries/zed/discussions/37270

[dawsh2]

I have a (somewhat) working extension here. I'm hoping to merge it with the existing Mermaid extension (disclaimer: I have no idea what I'm doing). It just uses the LSP as a JSON-RPC server for mmcd (Mermaid CLI). It's probably not idiomatic Zed, but it works for me and doesn't touch core code.

https://github.com/user-attachments/assets/b1b887bc-550f-4431-ad64-aceb6e6c7ed4

Currently it strips the mermaid code blocks away into .mermaid/*.mdd files (along with the SVGs, otherwise I had a hard time getting the code to stay out of the preview). You can still edit them with a "Edit Mermaid" command, though, so I actually kind of like it this way.