goldmark-mermaid

• Introduction
• Installation
• Usage
• Rendering
  • Rendering modes
  • Server-side rendering
• License

Introduction

goldmark-mermaid is an extension for the goldmark Markdown parser that adds support for Mermaid diagrams.

Demo: A web-based demonstration of the extension is available at https://abhinav.github.io/goldmark-mermaid/demo/.

Features

• Pluggable components
• Supports client-side rendering by injecting JavaScript
• Supports server-side rendering with the MermaidJS CLI or with your browser

Installation

Install the latest version of the library with Go modules.

go get go.abhg.dev/goldmark/mermaid@latest

Usage

To use goldmark-mermaid, import the mermaid package.

import "go.abhg.dev/goldmark/mermaid"

Then include the mermaid.Extender in the list of extensions you build your goldmark.Markdown with.

goldmark.New(
  goldmark.WithExtensions(
    // ...
    &mermaid.Extender{},
  ),
  // ...
).Convert(src, out)

The package supports Mermaid diagrams inside fenced code blocks with the language mermaid. For example,

When you render the Markdown as HTML, these will be rendered into diagrams.

You can also render diagrams server-side if you have a Chromium-like browser installed. See Rendering with CDP for details.

Rendering

Rendering methods

goldmark-mermaid supports two rendering modes:

• Client-side:
  Diagrams are rendered in-browser by injecting MermaidJS
  into the generated HTML.
• Server-side:
  Diagrams are rendered at the time the HTML is generated.
  The browser receives only the final SVGs.

You can pick between these by setting the RenderMode field.

goldmark.New(
  goldmark.WithExtensions(
    &mermaid.Extender{
      RenderMode: mermaid.RenderModeServer, // or RenderModeClient
    },
  ),
  // ...
).Convert(src, out)

A third automatic mode is provided as a convenience. It automatically picks between client-side and server-side rendering based on other configurations and system functionality. This mode is the default.

Server-side rendering

goldmark-mermaid offers two options for server-side rendering:

• CLI-based rendering
  invokes the MermaidJS CLI (mmdc) on your system to render diagrams
• CDP-based rendering
  uses Chrome DevTools Protocol to drive a headless browser on your system,
  and uses it to render diagrams

Rendering with the MermaidJS CLI

If server-side rendering is chosen, by default, the CLI-based renderer is used. You can request it explicitly by supplying a CLICompiler to mermaid.Extender or mermaid.ServerRenderer.

&mermaid.Extender{
  Compiler: &mermaid.CLICompiler{
    Theme: "neutral",
  },
}

By default, the CLICompiler will search for mmdc on your $PATH. Specify an alternative path with the CLI field:

&mermaid.CLICompiler{
  CLI: mermaid.MMDC(pathToMMDC),
}

Rendering with Chrome DevTools Protocol

If you have a Chromium-like browser installed on your system goldmark-mermaid can spin up a long-running headless process of it, and use that to render MermaidJS diagrams.

To use this, first download a minified copy of the MermaidJS source code. You can get it from https://cdn.jsdelivr.net/npm/mermaid@latest/dist/mermaid.min.js. Embed this into your program with go:embed.

import _ "embed" // needed for go:embed

//go:embed mermaid.min.js
var mermaidJSSource string

Next, import go.abhg.dev/goldmark/mermaid/mermaidcdp, and set up a mermaidcdp.Compiler.

compiler, err := mermaidcdp.New(&mermaidcdp.Config{
  JSSource: mermaidJSSource,
})
if err != nil {
  panic(err)
}
defer compiler.Close() // Don't forget this!

Plug this compiler into the mermaid.Extender that you install into your Goldmark Markdown object, and use the Markdown object like usual.

md := goldmark.New(
  goldmark.WithExtensions(
    // ...
    &mermaid.Extender{
      Compiler: compiler,
    },
  ),
  // ...
)

md.Convert(...)

License

This software is made available under the BSD3 license.