Skip to content
Starlight client Mermaid

Getting Started

starlight-client-mermaid is a Starlight plugin which enables client-side support for Mermaid diagrams in Markdown/MDX content in a Starlight documentation site.

‘Client-side’ means the Mermaid diagrams are rendered to SVGs on the user’s browser, as opposed to generating them on the server. This is mostly to avoid the hard requirement of installing an headless browser for server-based solutions, something that can cause troubles in some CI configurations. Also, server-based still requires some config fiddling and client-side scripting to properly support theme switching.

However, there are drawbacks for this client-side implementation:

  • MermaidJS code has to be fetched and run by the client. It has a modular architecture to import only the necessary code for the diagram types actually used, but still, the core only is around 450Kb uncompressed. It means also the rendering perfs will depend on the client setup ;
  • Diagrams will be rendered after the page is loaded, meaning there will be a loading and relayout effect ;
  • No cache: diagrams will be re-rendered each time the user reloads or revisits a page.

Installation

  1. The plugin package @pasqal-io/starlight-client-mermaid can be installed with your package manager of choice:

    Terminal window
    npm install @pasqal-io/starlight-client-mermaid

  2. Configure the plugin in your Starlight configuration in the astro.config.mjs file. See the plugin configuration page for available options.

    astro.config.mjs
    import starlight from '@astrojs/starlight'
    import { defineConfig } from 'astro/config'
    import starlightClientMermaid from '@pasqal-io/starlight-client-mermaid'
    

    export default defineConfig({
      integrations: [
        starlight({
          plugins: [starlightClientMermaid({ /* options */ })],
          title: 'My Docs',
        }),
      ],
    })

  3. Start the development server to preview the plugin in action.