Mermaid Diagrams

Mermaid Diagrams (mermaid)

Defines the map of settings for the Platen’s Mermaid diagrams markup option. The existing value is a map that includes whether or not to enable the markup rendering, which version of Mermaid to use, and what container element to render the diagrams in by default.

With this markup enabled, you can use Mermaid to create diagrams including flowcharts, pie charts, and sequence diagrams with a codeblock.

You can add new keys or replace the values for existing ones. You don’t need to keep the full list of all properties in your own configuration file. Only specify the values you want to add or replace.

Metadata

ID

https://platen.io/modules/platen/config/site/markup/mermaid/schema.json

Type

object

JSON Schema

Definition
{
  "$id": "https://platen.io/modules/platen/config/site/markup/mermaid/schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "Defines the settings for the Mermaid diagram markup option\n\nhttps://platen.io/modules/platen/config/site/markup/mermaid/",
  "properties": {
    "aliases": {
      "description": "Defines additional language IDs for the codeblock render hook.\n\nhttps://platen.io/modules/platen/config/site/markup/mermaid/#aliases",
      "oneOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "string"
        }
      ],
      "title": "Aliases"
    },
    "container": {
      "default": "pre",
      "description": "Specify the container element for Mermaid diagrams.\n\nhttps://platen.io/modules/platen/config/site/markup/mermaid/#container",
      "title": "Container Element",
      "type": "string"
    },
    "enabled": {
      "default": true,
      "description": "Choose whether Mermaid diagram rendering is available for the site.\n\nhttps://platen.io/modules/platen/config/site/markup/mermaid/#enabled",
      "title": "Enable Mermaid",
      "type": "boolean"
    },
    "partials": {
      "description": "Define a map of partials for Platen to inject as needed.\n\nhttps://platen.io/modules/platen/config/site/markup/mermaid/#partials",
      "properties": {
        "header": {
          "default": "platen/markup/mermaid/header",
          "description": "Injects a partial into the HTML header.\n\nhttps://platen.io/modules/platen/config/site/markup/mermaid/#header",
          "title": "Header Partial",
          "type": "string"
        },
        "renderers": {
          "description": "Registers one or more partials that act as render hooks.\n\nhttps://platen.io/modules/platen/config/site/markup/mermaid/#renderers",
          "properties": {
            "codeblock": {
              "default": "platen/markup/mermaid/codeblock",
              "description": "Adds a partial to call when processing the codeblock render hook.\n\nhttps://platen.io/modules/platen/config/site/markup/mermaid/#codeblock",
              "title": "Codeblock Render Hook Partial",
              "type": "string"
            }
          },
          "title": "Renderer Partials",
          "type": "object"
        }
      },
      "title": "Feature Partials",
      "type": "object"
    },
    "version": {
      "default": "10",
      "description": "Specify the version of Mermaid to load when needed.\n\nhttps://platen.io/modules/platen/config/site/markup/mermaid/#version",
      "title": "Mermaid Version",
      "type": "string"
    }
  },
  "title": "Mermaid Diagrams",
  "type": "object"
}

Enable Mermaid (enabled)

Choose whether the site renders Mermaid diagrams. The default is true.

Metadata

Type

boolean

Mermaid Version (version)

Specifies the version of Mermaid to load when needed. The Mermaid feature retrieves the style and script modules for Mermaid from a CDN at build time. This value is used to determine which version to bundle with the site and use for auto-rendering.

You can set this value to any valid released version of Mermaid greater than 10. The default is 10.

Metadata

Type

string

Container Element (container)

Specify the container element for Mermaid diagrams to render inside. By default, diagrams are rendered in a <pre> element. This setting can be overridden on a per-diagram basis with the container attribute or YAML option.

Switching this value to div or aside will remove the default styling for pre. The [sref:<aside>] element is useful for semantically indicating that the diagram is only indirectly related to the rest of the content.

Metadata

Type

string

Aliases (aliases)

Define one or more language IDs to use in addition to the default language IDs for codeblocks that render Mermaid diagrams. The default language ID is mermaid.

You can specify a string or an array of strings. If the value is an array, each item in the array is added as an alias.

Metadata

Must be one of

Type

array

Valid items

Type

string

Type

string

Feature Partials (partials)

Define a map of partials for Platen to inject as needed. These partials are only injected when enabled is set to true.

Metadata

Type

object

Renderer Partials (renderers)

Defines a map of partials to use as Markdown render hooks. Like all partials, these are only processed when enabled is set to true.

Supported renderer partials include:

  • codeblock, processed for fenced code blocks with a language ID
  • heading, processed for headings
  • image, processed for image links
  • link, processed for non-image links

In all cases, all renderer partials for enabled features and markup options are checked one after the other unless they return a render string. Only the first applicable partial that returns a render string is processed and rendered.

Metadata

Type

object

Codeblock Render Hook Partial (codeblock)

Adds support for Mermaid markup rendering for content. This render hook is only processed when the language ID for a codeblock is mermaid.

It registers the current page as having Mermaid, which ensures the library and style modules are loaded for automatic rendering.

It renders the codeblock’s definition inside a pre element by default. With the class attribute, it adds the specified classes to the element. With the id attribute, it adds an ID to the element, making it easier to link to.

It supports the new initialize directives for Mermaid, allowing you to override Mermaid’s configuration on a per-diagram basis.

It has handling for rendering the diagram inside a figure element as well, if the definition includes the <!-- Mermaid --> separator between the figure’s options and the Mermaid syntax.

For more information about authoring Mermaid diagrams in Platen, see Mermaid Diagrams in the reference documentation.

This value defaults to platen/markup/mermaid/codeblock. You can replace it with a different value, defining a new partial, or override the existing partial by creating the file layouts/partials/platen/markup/mermaid/codeblock.html in your own site or module.

For more information about defining codeblock render hook partials, see Defining a Codeblock Render Hook Partial in the Theme Guide.

Metadata

Type

string

Header Partial (header)

If specified, this partial is processed in the HTML header with the current page’s context. The default value is platen/markup/mermaid/header. You can overwrite this value, replacing it with another partial entirely, or you can add the same file to your own theme or site, effectively replacing it.

The default partial pulls the Mermaid style and library modules from a CDN if the page content includes any codeblocks with the mermaid language ID.

With the modules loaded, the page will automatically render any valid Mermaid markup on page, displaying the diagrams.

Metadata

Type

string
Edit this page