@sat-valorisation/jsdoc-mermaid

jsdoc-mermaid

A plugin that parses your JSDocs for Mermaid syntax and renders the diagrams and flowcharts described.

This is a fork of jsdoc-mermaid.

Getting Started

# install as a local dependency
yarn add -D jsdoc-mermaid # OR npm install -D jsdoc-mermaid

And then add jsdoc-mermaid to your jsdoc configuration file. That's it!

{
    "plugins": ["jsdoc-mermaid"]
}

Usage

Document a method with an @mermaid tag using JSDoc Syntax, like so:

/**
 * Represents a book.
 * @constructor
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 *
 * @mermaid
 *   graph TD;
 *     A-->B;
 *     A-->C;
 *     B-->D;
 *     C-->D;
 */
function Book(title, author) {
  /* ... */
}

Generate your JSDocs using the configuration you've specified - for instance:

jsdoc book.js -c conf.json

When you open that page in JSDoc, you should have a shiny new graph!

Customizing Mermaid

You can optionally include a section in your JSDoc configuration file (such as conf.json) to define Mermaid custom configurations. Simply add a section called "mermaid":

{
  "mermaid": {
    "theme": "forest"
  }
}

This package also supports some new properties to the mermaid configuration:

• version: Let's you specify which Mermaid version to use. If not provided, defaults to latest Mermaid.
• style: Let's you add optional CSS styles to the surrounding <div> tag (which also has class mermaid if you want to use a proper stylesheet).
• disableScript: When true, disables the generation of the script for including Mermaid and initializing it. This is sometimes needed when using a template that already has Mermaid scripting. Continues to provide <div class="mermaid"> around the @mermaid sections.

{
  "mermaid": {
    "theme": "nuetral",
    "style": "display: flex",
    "version": "8.3.0",
    "flowchart": {
      "curve": "cardinal",
      "htmlLabels": false
    }
  }
}

Mermaid configuration documentation

• Mermaid API, however the properties are often incorrect
• Mermaid configuration defaults shows the defaults, and appears to be more accurate
• Source code for the API which is harder to parse but the most accurate

Built With

• Mermaid - Generation of diagram and flowchart from text in a similar manner as markdown
• Doctrine - JSDoc parser

Versioning

We use SemVer for versioning.