Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Community Plugin
View plugin on GitHub


github actions npm version npm downloads prettier

Create mermaid graphs and diagrams in your markdown files.

This plugin uses remark-mermaidjs to generate SVG diagrams at build time. The mermaid code blocks are replaced with an inline SVG in the generated HTML. This prevents any runtime dependencies on mermaid.

Table of COntents


npm install gatsby-remark-mermaid gatsby-transformer-remark


Configure this plugin as a plugin of gatsby-transformer-remark.

NOTE: Make sure you add this plugin before any other plugins that process code blocks.

Example configuration

// In your gatsby-config.js
module.exports = {
  plugins: [
      resolve: 'gatsby-transformer-remark',
      options: {
        plugins: [
            resolve: `gatsby-remark-mermaid`,
            options: /** @type {import('gatsby-remark-mermaid').Options} */ ({
              mermaidConfig: {
                theme: 'neutral',
                themeCSS: '.node rect { fill: #fff; }'



The Playwright browser to use. (object, default: chromium)


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)


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:

  • node: The mdast code node that couldn’t be rendered.
  • error: The error message that was thrown.
  • file: The file on which the error occurred.


The options used to launch the browser. (object)


The mermaid config to use.


A custom prefix to use for Mermaid IDs. (string, default: mermaid)


This package was originally developed by Thomas Biesaart.


MIT © Thomas Biesaart

© 2023 Gatsby, Inc.