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 RazrFalcon/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]

old answer

Hey, @delucis just out of curiosity why Astro default highlighter is at remark level instead of rehype? Is there some technical reason for it or it's just historically this way?

For example, @shikijs/rehype works in Astro. And this is the same highlighter that Astro uses, but at rehype level.

I was wrong with my assumption. Astro uses rehype for code highlighting. The problem is that it loads highlighter before any other rehype plugins:

	if (!isPerformanceBenchmark) {
		// Syntax highlighting
		if (syntaxHighlight === 'shiki') {
			parser.use(rehypeShiki, shikiConfig);
		} else if (syntaxHighlight === 'prism') {
			parser.use(rehypePrism);
		}
	}

	// User rehype plugins
	for (const [plugin, pluginOpts] of loadedRehypePlugins) {
		parser.use(plugin, pluginOpts);
	}

For Astro solution can be:

import { defineConfig } from "astro/config";
import { rehypeShiki, markdownConfigDefaults } from "@astrojs/markdown-remark";
import rehypeMermaid from "rehype-mermaid";

// https://astro.build/config
export default defineConfig({
  markdown: {
    syntaxHighlight: false,
    rehypePlugins: [
      rehypeMermaid,
      [rehypeShiki, markdownConfigDefaults.shikiConfig],
    ],
  },
});

Need to check if it will work for Starlight though

[stereobooster]

old answer

Here is very hacky way (but the point is that rehypeMermaid works out of the box if it would be possible to put it before rehypeExpressiveCode):

import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";
import rehypeMermaid from "rehype-mermaid";
import { astroExpressiveCode, addClassName } from "astro-expressive-code";

export default defineConfig({
  integrations: [
    // astroExpressiveCode inserted before starlight it inserts `rehypeExpressiveCode` after `rehypeMermaid` and it works
    astroExpressiveCode({ ... }),
    starlight({ ... }),
  ],
  markdown: {
    rehypePlugins: [rehypeMermaid],
  }
})

Can this be reported as bug?

How to configure astroExpressiveCode so it would look more like default Starlight style:

 astroExpressiveCode({
  customConfigPreprocessors: {
    preprocessAstroIntegrationConfig: () => {
      // Add the `not-content` class to all rendered blocks to prevent them from being affected
      // by Starlight's default content styles
      const plugins = [
        {
          name: "Starlight Plugin",
          hooks: {
            postprocessRenderedBlock: ({ renderData }) => {
              addClassName(renderData.blockAst, "not-content");
            },
          },
        },
      ];

      return {
        themeCssSelector: (theme, { styleVariants }) => {
          // If one dark and one light theme are available, and the user has not disabled it,
          // generate theme CSS selectors compatible with Starlight's dark mode switch
          if (styleVariants.length >= 2) {
            const baseTheme = styleVariants[0]?.theme;
            const altTheme = styleVariants.find(
              (v) => v.theme.type !== baseTheme?.type
            )?.theme;
            if (theme === baseTheme || theme === altTheme)
              return `[data-theme='${theme.type}']`;
          }
          // Return the default selector
          return `[data-theme='${theme.name}']`;
        },
        plugins,
      };
    },
  },
});

[delucis]

In our next release, we’ll be updating Expressive Code — see #1720 — not 100% sure, but it also moves stuff to rehype so might help.

[HiDeoo]

Starting with Starlight v0.22, which includes an update to Expressive Code transitioning from a remark plugin to a rehype plugin, the instructions shared by Chris above can be simplified a bit.

1. Install rehype-mermaid

   npm i rehype-mermaid

2. Add the Mermaid rehype plugin to astro.config.mjs:

   // astro.config.mjs
   import { defineConfig } from "astro/config";
   import starlight from "@astrojs/starlight";
   import rehypeMermaid from "rehype-mermaid";
   
   export default defineConfig({
     integrations: [
       starlight({
         title: "My Docs",
       }),
     ],
     markdown: {
       rehypePlugins: [rehypeMermaid],
     },
   });

[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

[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