@k9n/scully-plugin-mermaid

scully-plugin-mermaid - The mermaid postRenderer

Installation

To install this library with npm run:

npm i @k9n/scully-plugin-mermaid mermaid-render -D

Usage

Apply the postRenderer plugin via your Scully config file (scully.<project-name>.config.ts):

import { ScullyConfig, setPluginConfig } from '@scullyio/scully';
/** this loads the default render plugin, remove when switching to something else. */
import '@scullyio/scully-plugin-puppeteer';
import '@k9n/scully-plugin-mermaid';
import { MermaidPluginName, MermaidPluginConfig } from '@k9n/scully-plugin-mermaid';

const mermaidOptions: MermaidPluginConfig = {
  /**
   * OPTIONAL: '.language-mermaid' is also the default, so no need to define this
   */
  selector: '.language-mermaid',
  /**
   * OPTIONAL: Define the wrapper element for the SVG
   * When undefined or set to `true`, a `div` with the class `mermaid-svg` is used by default
   * When set to `false`: No wrapper is used (SVG is added directly)
   * When defined as an object, `tagName` is needed to define the type of the wrapper element (HTML tag)
   */
  wrapper: {
    tagName: 'div', // necessary when object is defined
    classNames: ['wrapper', 'mermaid-svg'], // optional
  },
  /**
   * configuration for the mermaid plugin
   * All params as defined here are valid:
   * https://mermaid-js.github.io/mermaid/getting-started/Setup.html#mermaidapi-configuration-defaults
   */
  config: {
    theme: 'dark',
  }
};
setPluginConfig(MermaidPluginName, mermaidOptions);

export const config: ScullyConfig = {
  projectRoot: './src',
  projectName: 'scully-mermaid',
  outDir: './dist/static',
  routes: {
    '/blog/:slug': {
      type: 'contentFolder',
      postRenderers: [MermaidPluginName], // apply the postRenderer
      slug: {
        folder: './blog',
      },
    },
  },
};

By default, you don't need to add any options. The defaults from Mermaid will be used as described in the official docs. You can use any of the described mermaid config parameter.

Example

After running the postRenderer it will convert markdown content like the following into SVG graphics:

```mermaid
sequenceDiagram
    Alice ->> Bob: Hello Bob, how are you?
    Bob-->>John: How about you John?
    Bob--x Alice: I am good thanks!
    Bob-x John: I am good thanks!
    Note right of John: Some note.

    Bob-->Alice: Checking with John...
    Alice->John: Yes... John, how are you?
```

The above example will result in a graphic like this one:

The resulting SVG is wrapped into an HTML <div> element with the class mermaid-svg by default. This can be changed to other elements / classes by adjusting the options.