Fork me on GitHub
Built by Maven

Mermaid Diagrams

Doxia Sitetools can optionally embed the necessary Javascript to render Mermaid diagrams client-side (supported since m-site-p 3.22.0).

Setup

In order to enable this feature one has to add element mermaid to the Site Descriptor. Make sure the site descriptor references namespace 2.1.0 or newer.

Reference from external CDN

Although an empty element is enough, usually one wants to reference a specific Mermaid JS version from an external URL instead of embedding that into each site by yourself and reference it from there.

<site xmlns="http://maven.apache.org/SITE/2.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ...>
  ...
  <mermaid>
    <externalJsUrl integrity="sha384-1CMXl090wj8Dd6YfnzSQUOgWbE6suWCaenYG7pox5AX7apTpY3PmJMeS2oPql4Gk">https://cdn.jsdelivr.net/npm/mermaid@11.14.0/dist/mermaid.min.js</externalJsUrl>
  </mermaid>
  

</site>

It is strongly recommended to also set the integrity attribute in order to ensure the external source delivers exactly the script you expect. One can calculate the integrity for a specific Mermaid version with the online tool provided at https://srihash.org/. The default external source for Mermaid is jsDelivr.

Using the ECMAScript Module (ESM) URL is not yet supported.

Embed in generated site

To just embed the hardcoded version of Mermaid into your generated site (11.13.0 for Doxia 2.1.0) just leave out the externalJsUrl child element.

<site xmlns="http://maven.apache.org/SITE/2.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ...>
  ...
  <mermaid>
   ...
  </mermaid>
</site>

That way the JS is automatically copied to your site during the rendering and referenced accordingly in your HTML.

This should only be necessary if your site's Content Security Policy (CSP) prevents including JS from external sources (like for example the global Apache CSP).

Usage

In order to write Mermaid diagrams, one can just embed them in Doxia sources. For example to embed something in Markdown (md) write

This is my diagram:

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

This will be automatically rendered on client side (replacing the Mermaid source in the HTML page).

Configuration

One can further adjust the Mermaid configuration used for rendering with the config element in the site descriptor. Its format is described in MermaidConfig.