Mermaid support out of the box

[TheKnarf]

What version of starlight are you using?

N/A

What is your idea?

Starlight should support Mermaid diagrams either our of the box, or as an official plugin. It's really dumb that it doesn't

Why is this feature necessary?

Setting it up by yourself is a ton of work, and its really buggy.

You can do so by adding the following to astro.config.mjs:

import rehypeMermaid from 'rehype-mermaid';
import rehypeRaw from 'rehype-raw';
//...
	markdown: {
		rehypePlugins: [
			rehypeRaw,
			rehypeMermaid,
		],
	},

However if you do so you MDX support crashes. So you also have to add the following:

export default defineConfig({
  integrations: [
    starlight({
    // ...
    }),
   astroExpressiveCode(),
   mdx({
      // Markdown config now ignored
      extendMarkdownConfig: false,
      // No `remarkPlugins` applied
    }),
   ],
})

And after all of that work it only works when starlight is in light-mode, as it only generate styling for one mode out of the box. Adding support to integrate with starlights dark- and light-mode would be even more work.

This should ultimatly just be supported by startlight if they want to be serious alternative.

Do you have examples of this feature in other projects?

Docusaurus have an official plugin thats super easy to use

https://docusaurus.io/docs/markdown-features/diagrams

Participation

• I am willing to submit a pull request for this feature.

[stereobooster]

UPD see solution in the comment bellow #1259 (reply in thread)

Article about different configuration options https://astro-digital-garden.stereobooster.com/recipes/mermaid-diagrams-in-markdown/

old answer

I think I got to the bottom of the problem. There are two options:

remark-mermaidjs

Use remark-mermaidjs, so it would process code blocks before remark-shiki

But author (of the plugin) advice against it

rehype-mermaidjs

It would work with remark-shiki unless it would mess with <pre>/<code> tags.

In this case you need either:

• use rehype-raw, like in the original post
• ask Astro team to fix remark-shiki
• disable remark-shiki at all (markdown.syntaxHighlight: false) and use rehype-shikiji

PS

My post about Astro diagram solutions

[icelattefull]

None of the approaches listed above worked for me. However, this did

[delucis]

Not Mermaid, but sharing an Astro integration for the D2 diagramming language that @HiDeoo built that might also be of interest to people in this thread: https://astro-d2.vercel.app/

[stereobooster]

d2 uses playwright (and goja) the same as remark-mermaidjs. Funny that whatever we do - we get back to headless browsers

[HiDeoo]

To recap everything I learned while working on this:

• d2 only uses Playwright for PNG exports (reference)
• astro-d2 never exports to PNG
• remark-mermaidjs uses Playwright for all exports and is not recommended by its author who recommends using rehype-mermaid instead (reference)
• rehype-mermaid uses Playwright for all exports

[delucis]

I’m pretty sure PNG support could be added without Playwright too if desired using a tool like https://github.com/yisibl/resvg-js

[HiDeoo]

I’m pretty sure PNG support could be added without Playwright too if desired using a tool like yisibl/resvg-js

Definitely, this is even tracked by D2 but currently blocked by linebender/resvg#541

[stereobooster]

Thank you, @HiDeoo for pointing this out. Somehow I was sure it requires Playwright for everything. I will need to play with it more

[darrenparkinson]

Also interested in this capability. Pretty much makes it unusable for tech docs without it. We're currently testing with mdbook which you can add mermaid to very easily.

Docs currently built with Docker using this:

FROM rust as book-build
RUN cargo install mdbook
RUN cargo install mdbook-mermaid
WORKDIR /app
COPY --from=preparation-stage /app .
RUN mdbook build

We're not a rust shop though, so was looking at alternatives.

mkdocs also appears to support mermaid fairly easily too.

This would genuinely be a great addition out of the box.

[delucis]

EDIT: This answer is outdated. See @HiDeoo’s Mermaid solution below for the latest and simplest set-up.

Original comment

Just did some testing to get reype-mermaid working kind of OK and sharing notes here in case it’s helpful

1. A few dependencies are needed, mostly for massaging the remark/rehype pipeline to work nicely:

   npm i hast-util-from-html hast-util-to-html mdast-util-to-hast rehype-mermaid unist-util-visit

2. Add this module to your project. It exports an Astro integration that wires up rehype-mermaid with some small utilities to ensure code blocks are not transformed too early.

   // integrations/astro-rehype-mermaid.js
   
   import { fromHtml } from 'hast-util-from-html';
   import { toHtml } from 'hast-util-to-html';
   import { toHast } from 'mdast-util-to-hast';
   import { visit } from 'unist-util-visit';
   import rehypeMermaid from 'rehype-mermaid';
   
   /** Transform a mermaid code block to HTML before it gets syntax highlighted to preserve its structure. */
   const remarkMermaidToHtml = () => (tree) => {
     visit(tree, 'code', (code, index, parent) => {
       if (index === undefined || !parent) return;
       if (code.lang === 'mermaid') {
         const html = toHtml(toHast(code));
         parent.children.splice(index, 1, { type: 'html', value: html });
       }
     });
   };
   
   /** Transform a raw HTML node created from a mermaid code block back to a full HAST. */
   const rehypeMermaidRawToHast = () => (tree) => {
     visit(tree, 'raw', (node, index, parent) => {
       if (index === undefined || !parent) return;
       if (node.value.startsWith('<pre><code class="language-mermaid"')) {
         const hast = fromHtml(node.value, { fragment: true });
         parent.children.splice(index, 1, hast);
       }
     });
   };
   
   /**
    * Astro integration to set up `rehype-mermaid` to render Markdown code blocks with the `mermaid` language.
    * @param {import('rehype-mermaid').RehypeMermaidOptions} options
    * @return {import('astro').AstroIntegration}
    */
   export default function astroRehypeMermaid(options = {}) {
     return {
       name: 'astro-mermaid',
       hooks: {
         'astro:config:setup'({ updateConfig }) {
           updateConfig({
             markdown: {
               remarkPlugins: [remarkMermaidToHtml],
               rehypePlugins: [rehypeMermaidRawToHast, [rehypeMermaid, options]],
             },
           });
         },
       },
     };
   }

3. Import the astroRehypeMermaid integration into astro.config.mjs and add it to your integrations array:

   // astro.config.mjs
   import { defineConfig } from 'astro/config';
   import starlight from '@astrojs/starlight';
   import astroRehypeMermaid from './integrations/astro-rehype-mermaid';
   
   export default defineConfig({
     integrations: [
       astroRehypeMermaid({
         // rehype-mermaid options can be passed here
       }),
       starlight({
         title: 'My Docs',
       }),
     ],
   });

I didn’t get far enough to work out if there’s a nicer way to handle dark/light mode support, but maybe this is a good starting point for someone to iterate on or even publish as a community package!

[stereobooster]

Thank you very much for fixing it.

export default defineConfig({
  markdown: {
    rehypePlugins: [[rehypeMermaid, { strategy: "img-svg", dark: true }]],
  },
});

Does anybody know how to solve issue with dark mode? #1829

[TeenBiscuits]

I have a problem with this implementation and it is the dependency on playwright. If you try to deploy your website to vercel there is no way to use playwright because you can't install system packages.

Details Vercel Logs

╔══════════════════════════════════════════════════════╗
║ Host system is missing dependencies to run browsers. ║
║ Please install them with the following command:      ║
║                                                      ║
║     pnpm exec playwright install-deps                ║
║                                                      ║
║ Alternatively, use apt:                              ║
║     apt-get install libnss3\                         ║
║         libnspr4\                                    ║
║         libgbm1                                      ║
║                                                      ║
║ <3 Playwright Team                                   ║
╚══════════════════════════════════════════════════════╝

I use this implementation Adding Mermaid diagrams to Astro MDX - Xkonti.tech. If there is someone who knows how to use this package in vercel I would prefer to be able to use a rehype plugin.

By the way i use vercel SSR.

[HuakunShen]

@stereobooster how to make the theme reactive? Support both dark and light theme based on current page preference.

[stereobooster]

https://astro-digital-garden.stereobooster.com/recipes/mermaid-diagrams-in-markdown/ strategy: "img-class-dark-mode"

[asbjornu]

I got @HiDeoo's recipe in #1259 (reply in thread) to work after upgrading Astro from v4.2.8 to v4.16.18 and Starlight from v0.15.4 to v0.29.3.

[torn4dom4n]

I found this site which is so good to support Mermaid.

[stereobooster]

old answer

here is what they use https://github.com/paularmstrong/onerepo/blob/main/docs/src/plugins/remark-mermaid.ts

import type { RemarkPlugin } from '@astrojs/markdown-remark';
import { visit } from 'unist-util-visit';

const escapeMap: Record<string, string> = {
	'&': '&amp;',
	'<': '&lt;',
	'>': '&gt;',
	'"': '&quot;',
	"'": '&#39;',
};

const escapeHtml = (str: string) => str.replace(/[&<>"']/g, (c) => escapeMap[c]);

export const mermaid: RemarkPlugin<[]> = () => (tree) => {
	visit(tree, 'code', (node) => {
		if (node.lang !== 'mermaid') return;

		// @ts-ignore
		node.type = 'html';
		node.value = `<div class="mermaid" data-content="${escapeHtml(node.value)}"><p>Loading graph...</p></div>`;
	});
};

[torn4dom4n]

Yeah, I know it. But I still hope we have an integratetion or component to support this.

[stereobooster]

Related: implemented small library to add pan/zoom functionality to SVG, img - https://github.com/stereobooster/svg-pan-zoom-gesture

[stereobooster]

Just in case if anybody is interested, rehype-raw that is used by Astro may cause issues for some diagrams. For example, remcohaszing/rehype-mermaid#17

[ematipico]

Now that Astro allows us to exclude languages, I think it's possible to integrate the support out of the box with little changes: https://docs.astro.build/en/reference/configuration-reference/#markdownsyntaxhighlightexcludelangs

[delucis]

I don’t think we were impacted that because Expressive Code already handled it and we’re not using Astro’s Shiki instance. The main reason not to support it out of the box is just that Mermaid is a large, slow, somewhat old-fashioned package, so bundling it with Starlight is probably not a great idea. A third-party plugin for Starlight would probably be the best approach to allow people to add Mermaid support when they need it.

[HiDeoo]

Please refrain from posting advertisements for your paid services in this GitHub repository. This is an open-source project community, and we encourage collaboration and sharing of knowledge without any commercial intent. Thank you for your understanding!

[pppwaw]

I found a repo astro-mermaid which provides client-side Mermaid support. It works well for me!