mermaid

README

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

Usage

To use goldmark-mermaid, import the mermaid package.

import mermaid "github.com/abhinav/goldmark-mermaid"

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

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

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

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

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

Rendering diagrams

Mermaid diagrams can be rendered at the time the file is processed ("server-side") or in-browser when the file is viewed ("client-side").

• With server-side rendering, goldmark-mermaid calls out to the MermaidJS CLI to render SVGs inline into the document.
• With client-side rendering, goldmark-mermaid generates HTML that renders diagrams in-browser.

You can pick between the two by setting RenderMode on mermaid.Extender.

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

By default, goldmark-mermaid will pick between the two, based on whether it was able to find the mmdc executable on your $PATH.

Documentation

Overview

Package mermaid adds support for Mermaid diagrams to the Goldmark Markdown parser.

Deprecated: Use "go.abhg.dev/markdown/mermaid" instead.

Index

• Constants
• Variables
• type Block
• type CLI
• type ClientRenderer
• type Extender
• type MMDC
• type RenderMode
• type Renderer
• type ScriptBlock
• type ServerRenderer
• type Transformer

Constants

const (
	// RenderModeAuto picks the renderer
	// based on the availability of the Mermaid CLI.
	//
	// If the 'mmdc' CLI is available on $PATH,
	// this will generate diagrams server-side.
	// Otherwise, it'll generate them client-side.
	RenderModeAuto = mermaid.RenderModeAuto

	// RenderModeClient renders Mermaid diagrams client-side
	// by adding <script> tags.
	RenderModeClient = mermaid.RenderModeClient

	// RenderModeServer renders Mermaid diagrams server-side
	// using the Mermaid CLI.
	//
	// Fails rendering if the Mermaid CLI is absent.
	RenderModeServer = mermaid.RenderModeServer
)

Variables

var DefaultMMDC = mermaid.DefaultMMDC

DefaultMMDC is the default MMDC implementation used for server-side rendering.

It calls out to the 'mmdc' executable to generate SVGs.

var Kind = mermaid.Kind

Kind is the kind of a Mermaid block.

var ScriptKind = mermaid.ScriptKind

ScriptKind is the kind of a Mermaid Script block.

Types

type Block

type Block = mermaid.Block

Block is a Mermaid block.

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

Its raw contents are the plain text of the Mermaid diagram.

type CLI

type CLI = mermaid.CLI

CLI is a basic implementation of MMDC.

type ClientRenderer

type ClientRenderer = mermaid.ClientRenderer

ClientRenderer renders Mermaid diagrams as HTML, to be rendered into images client side.

It operates by installing a <script> tag into the document that renders the Mermaid diagrams client-side.

type Extender

type Extender = mermaid.Extender

Extender adds support for Mermaid diagrams to a Goldmark Markdown parser.

Use it by installing it to the goldmark.Markdown object upon creation.

goldmark.New(
	// ...
	goldmark.WithExtensions(
		// ...
		&mermaid.Exender{
			RenderMode: mermaid.ServerRenderMode,
		},
	),
)

type MMDC

type MMDC = mermaid.MMDC

MMDC provides access to the MermaidJS CLI.

type RenderMode

type RenderMode = mermaid.RenderMode

RenderMode specifies which renderer the Extender should use.

type Renderer

type Renderer = ClientRenderer

Renderer is the client-side renderer for Mermaid diagrams.

Deprecated: Use ClientRenderer.

type ScriptBlock

type ScriptBlock = mermaid.ScriptBlock

ScriptBlock marks where the Mermaid Javascript will be included.

This is a placeholder and does not contain anything.

type ServerRenderer

type ServerRenderer = mermaid.ServerRenderer

ServerRenderer renders Mermaid diagrams into images server-side.

It operates by replacing mermaid code blocks in your document with SVGs.

type Transformer

type Transformer = mermaid.Transformer

Transformer transforms a Goldmark Markdown AST with support for Mermaid diagrams. It makes the following transformations:

• replace mermaid code blocks with mermaid.Block nodes
• add a mermaid.ScriptBlock node if the document uses Mermaid and one does not already exist