Mermaid

Enabling using Mermaid diagrams on this blog and snippets. Mermaid is a simple markdown-like script language for generating charts from text via javascript.

• mxd-mermaid - Plug and play Mermaid in MDX
• mermaid - Markdownish syntax for generating flowcharts, sequence diagrams, class diagrams, gantt charts and git graphs.

Install

pnpm add mdx-mermaid@^v1.3.0 mermaid

Then I wrote a MermaidGraph component to render the Mermaid component with the proper theme (dark or light) based on next-theme. Note it also delays loading the Mermaid graph to avoid the Error: Text content does not match server-rendered HTML. caused by server side rendering delay of the Mermaid graph.

import { Mermaid } from 'mdx-mermaid/Mermaid';
import { useTheme } from 'next-themes';
import { useEffect, useState } from 'react';

/**
 * This is a wrapper for Mermaid that avoids `Error: Text content does not match server-rendered HTML.`
 * I believe this just force client-side rendering. An added benefit is that it allows toggling the
 * theme based on next-themes.
 * @param chart - the mermaid chart as string
 * @returns
 */
export function MermaidGraph({ chart }) {
  const [showChild, setShowChild] = useState(false);
  useEffect(() => {
    setShowChild(true);
  }, []);

  if (!showChild) {
    return <h1 className="text-jacarta-400">Loading diagram...</h1>;
  }
  return <MermaidWithTheme chart={chart} />;
}

export function MermaidWithTheme({ chart }) {
  const { resolvedTheme } = useTheme();
  return (
    <Mermaid
      chart={chart}
      config={{ mermaid: { theme: resolvedTheme } }}
    />
  );
}

export default MermaidGraph;

The snippets page then instanciates an MDX component supporting Mermaid graphs.

import Mermaid from 'components/MermaidGraph';

const components = {
  Mermaid,
};

export default function SnippetPage(snippet: Snippet) {
  const Component = useMDXComponent(snippet.body.code);

  return (
    <SnippetLayout snippet={snippet}>
      <Component components={components} />
    </SnippetLayout>
  );
}

Finally with MDX you can use the Mermaid React component like this:

<Mermaid chart={`graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
`} />

Now it would be great if I can figure out how to configure MDX to parse mermaid blocks as Mermaid graphs. Let me please know if you you have a pointer.

Examples: GitGraph

 gitGraph
       commit
       commit
       branch develop
       checkout develop
       commit
       commit
       checkout main
       merge develop
       commit
       commit

Loading diagram...

See GitGraph documentation for more examples.

Examples: Sequence Diagram

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts <br/>prevail!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!

Loading diagram...

And you can find way more graphs styles at See https://github.com/mermaid-js/mermaid