rehype-mermaid


A rehype plugin to render mermaid diagrams.

Table of Contents

- Installation
- Usage
- 'img-png'
- 'img-svg'
- 'inline-svg'
- 'pre-mermaid'
- API
- unified().use(rehypeMermaid, options?)
- Examples
- remark
- MDX
- Compatibility
- Related Projects
- Contributing
- Acknowledgements
- License

Installation

``sh
npm install rehype-mermaid
`

Outside of browsers rehype-mermaid uses Playwright. If you use this
outside of a browser, you need to install Playwright and a Playwright browser.

`sh
npm install playwright
npx playwright install --with-deps chromium
`

See the Playwright Browsers documentation for more
information.

Usage

This plugin takes all

 and  elements, and
replaces them with a rendered version of the diagram. If the  element is wrapped in a
 element, the 
 element is replaced as well. This is compatible with what Mermaid would
render client side, as well as the output of mermaid code blocks processed by
remark-rehype.
The plugin has several rendering strategies described below.
Given a file named index.html:
`html

  
    
  
  
    

      graph TD;
          A-->B;
          A-->C;
          B-->D;
          C-->D;
    

    

      graph TD;
          A-->B;
          A-->C;
          B-->D;
          C-->D;
    

  

`
The following script:
`js
import { readFile } from 'node:fs/promises'
import { rehype } from 'rehype'
import rehypeMermaid from 'rehype-mermaid'
const { value } = await rehype()
  .use(rehypeMermaid, {
    // The default strategy is 'inline-svg'
    // strategy: 'img-png'
    // strategy: 'img-svg'
    // strategy: 'inline-svg'
    // strategy: 'pre-mermaid'
  })
  .process(await readFile('index.html'))
console.log(value)
`
Yields the following results, depending on the stragey used.
$3
This strategy renders a diagram as an  element with an inline base64 PNG image. Given the
example, this yields:
`html

  
    
  
  
    
    
  

`
This strategy is asynchronous.
This strategy supports the dark option.
$3
This strategy renders a diagram as an  element with an inline SVG image. Given the example,
this yields:
`html

  
    
  
  
    
    
  

`
This strategy is asynchronous.
This strategy supports the dark option.
$3
This strategy renders a diagram as an inline  element. Given the example, this yields:
`html

  
    
  
  
    
    
  

`
This strategy is asynchronous.
This strategy does not support the dark option.
$3
This strategy replaces the element with a 
 element with only the diagram as
its child. Given the example, this yields:
`html

  
    
  
  
    

      graph TD;
          A-->B;
          A-->C;
          B-->D;
          C-->D;
    

    

      graph TD;
          A-->B;
          A-->C;
          B-->D;
          C-->D;
    

  

`
This allows Mermaid to render the diagram on the client side, for example using:
`js
import mermaid from 'mermaid'
mermaid.initialize({ startOnLoad: true })
`
This strategy is synchronous.
This strategy does not support the dark option.
API
This package has a default export rehypeMermaid.
$3
#### options
##### browser
The Playwright browser to use. (object, default: chromium)
##### colorScheme
The default color scheme.
If not specified, rehype-mermaid will determine the color scheme based on the color-scheme meta
tag. If this doesn’t exist, the default color scheme is light. (string)
##### css
A URL that points to a custom CSS file to load. Use this to load custom fonts. This option is
ignored in the browser. You need to include the CSS in your build manually. (string | URL)
##### dark
If specified, add responsive dark mode using a  element.
This option is only supported by the img-png and img-svg strategies.
##### errorFallback
Create a fallback node if processing of a mermaid diagram fails. If nothing is returned, the code
block is removed. The function receives the following arguments:
- element The hast element that could not be rendered.
- diagram The Mermaid diagram that could not be rendered as a string.
- error: The error that was thrown.
- file: The file on which the error occurred.
##### launchOptions
The options used to launch the browser. (object)
##### mermaidConfig
A custom Mermaid configuration. By default fontFamily is set to arial,sans-serif. This option is
ignored in the browser. You need to call mermaid.initialize() manually. (object)
##### prefix
A custom prefix to use for Mermaid IDs. (string, default: mermaid)
##### strategy
The render strategy to use. One of 'img-png', 'img-svg',
'inline-svg', or 'pre-mermaid'. (default:
'inline-svg')
Examples
$3
This package works with Mermaid codeblocks in markdown using
remark-parse,
remark-rehype, and
rehype-stringify.
`js
import rehypeMermaid from 'rehype-mermaid'
import rehypeStringify from 'rehype-stringify'
import remarkParse from 'remark'
import remarkRehype from 'remark-rehype'
import { unified } from 'unified'
const processor = unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeMermaid)
  .use(rehypeStringify)
const markdown = 
Mermaid Diagram
\\\mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
\\\
const { value } = await processor.process(markdown)
console.log(value)
`
$3
This package works with Mermaid codeblocks in MDX.
`js
import { compile } from '@mdx-js/mdx'
import rehypeMermaid from 'rehype-mermaid'
const mdx = 
Mermaid Diagram
\\\mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
\\\
const { value } = await compile(mdx, {
  rehypePlugins: [rehypeMermaid]
})
console.log(value)
`
Compatibility
This project is compatible with Node.js 18 or greater. It’s compatible with mermaid code blocks
processed by remark-rehype. This means it’s also
compatible with MDX.
Related Projects
- mermaid is the library that’s used to render the diagrams.
- mermaid-isomorphic allows this package to
  render Mermaid diagrams in both Node.js and the browser.
- rehype` provides HTML processing using a
  unified pipeline.
Contributing
Test fixtures are generated and verified using Linux. Rendering on other platforms may yield
slightly different results. Don’t worry about adding new fixtures, but don’t update existing ones
that cause CI to fail. Furthermore see my global
contributing guidelines.
Acknowledgements
Thanks to @bitekong for giving me the npm package name.
License
MIT © Remco Haszing