mermaid

README

goldmark-mermaid

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/.

Installation

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,

```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(
  goldmark.WithExtensions(
    &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.

Index

• Variables
• type Block
  • func (b *Block) Dump(src []byte, level int)
  • func (*Block) IsRaw() bool
  • func (*Block) Kind() ast.NodeKind
• type CLI
  • func (c *CLI) Command(args ...string) *exec.Cmd
• type ClientRenderer
  • func (r *ClientRenderer) RegisterFuncs(reg renderer.NodeRendererFuncRegisterer)
  • func (r *ClientRenderer) Render(w util.BufWriter, src []byte, node ast.Node, entering bool) (ast.WalkStatus, error)
  • func (r *ClientRenderer) RenderScript(w util.BufWriter, _ []byte, node ast.Node, entering bool) (ast.WalkStatus, error)
• type Extender
  • func (e *Extender) Extend(md goldmark.Markdown)
• type MMDC
• type RenderMode
  • func (i RenderMode) String() string
• type ScriptBlock
  • func (b *ScriptBlock) Dump(src []byte, level int)
  • func (*ScriptBlock) IsRaw() bool
  • func (*ScriptBlock) Kind() ast.NodeKind
• type ServerRenderer
  • func (r *ServerRenderer) RegisterFuncs(reg renderer.NodeRendererFuncRegisterer)
  • func (r *ServerRenderer) Render(w util.BufWriter, src []byte, node ast.Node, entering bool) (ast.WalkStatus, error)
• type Transformer
  • func (t *Transformer) Transform(doc *ast.Document, reader text.Reader, _ parser.Context)

Examples

• Extender

Variables

var DefaultMMDC = new(defaultMMDC)

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

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

var Kind = ast.NewNodeKind("MermaidBlock")

Kind is the kind of a Mermaid block.

var ScriptKind = ast.NewNodeKind("MermaidScriptBlock")

ScriptKind is the kind of a Mermaid Script block.

Types

type Block

type Block struct {
	ast.BaseBlock
}

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.

func (*Block) Dump

func (b *Block) Dump(src []byte, level int)

Dump dumps the contents of this block to stdout.

func (*Block) IsRaw

func (*Block) IsRaw() bool

IsRaw reports that this block should be rendered as-is.

func (*Block) Kind

func (*Block) Kind() ast.NodeKind

Kind reports that this is a MermaidBlock.

type CLI

type CLI struct {
	// Path to the "mmdc" executable.
	//
	// If unspecified, search $PATH for it.
	Path string
}

CLI is a basic implementation of MMDC.

func (*CLI) Command

func (c *CLI) Command(args ...string) *exec.Cmd

Command builds an exec.Cmd to run 'mmdc' with the given arguments.

type ClientRenderer

type ClientRenderer struct {
	// URL of Mermaid Javascript to be included in the page.
	//
	// Defaults to the latest version available on cdn.jsdelivr.net.
	MermaidJS string

	// ContainerTag is the name of the HTML tag to use for the container
	// that holds the Mermaid diagram.
	// The name must be without the angle brackets.
	//
	// Defaults to "pre".
	ContainerTag string
}

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.

func (*ClientRenderer) RegisterFuncs

func (r *ClientRenderer) RegisterFuncs(reg renderer.NodeRendererFuncRegisterer)

RegisterFuncs registers the renderer for Mermaid blocks with the provided Goldmark Registerer.

func (*ClientRenderer) Render

func (r *ClientRenderer) Render(w util.BufWriter, src []byte, node ast.Node, entering bool) (ast.WalkStatus, error)

Render renders mermaid.Block nodes.

func (*ClientRenderer) RenderScript

func (r *ClientRenderer) RenderScript(w util.BufWriter, _ []byte, node ast.Node, entering bool) (ast.WalkStatus, error)

RenderScript renders mermaid.ScriptBlock nodes.

type Extender

type Extender struct {
	// RenderMode specifies which renderer the Extender should install.
	//
	// Defaults to AutoRenderMode, picking renderers
	// based on the availability of the Mermaid CLI.
	RenderMode RenderMode

	// URL of Mermaid Javascript to be included in the page.
	//
	// Ignored if NoScript is true
	// or if we're rendering diagrams server-side.
	//
	// Defaults to the latest version available on cdn.jsdelivr.net.
	MermaidJS string

	// HTML tag to use for the container element for diagrams.
	//
	// Defaults to "pre" for client-side rendering,
	// and "div" for server-side rendering.
	ContainerTag string

	// If true, don't add a <script> including Mermaid to the end of the
	// page even if rendering diagrams client-side.
	//
	// Use this if the page you're including goldmark-mermaid in
	// already has a MermaidJS script included elsewhere.
	NoScript bool

	// MMDC provides access to the Mermaid CLI.
	//
	// Ignored if we're rendering diagrams client-side.
	//
	// Uses DefaultMMDC if unset.
	MMDC MMDC

	// Theme for mermaid diagrams.
	//
	// Ignored if we're rendering diagrams client-side.
	//
	// Values include "dark", "default", "forest", and "neutral".
	// See MermaidJS documentation for a full list.
	Theme string
	// contains filtered or unexported fields
}

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

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

Example

package main

import (
	"github.com/yuin/goldmark"
	"go.abhg.dev/goldmark/mermaid"
)

func main() {
	goldmark.New(
		// ...
		goldmark.WithExtensions(
			&mermaid.Extender{
				RenderMode: mermaid.RenderModeServer,
			},
			// ...
		),
	)
}

func (*Extender) Extend

func (e *Extender) Extend(md goldmark.Markdown)

Extend extends the provided Goldmark parser with support for Mermaid diagrams.

type MMDC

type MMDC interface {
	// Command builds an exec.Cmd to run the Mermaid CLI
	// with the provided arguments.
	//
	// The list of arguments does not include 'mmdc' itself.
	Command(args ...string) *exec.Cmd
}

MMDC provides access to the MermaidJS CLI.

type RenderMode

type RenderMode int

RenderMode specifies which renderer the Extender should use.

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 RenderMode = iota

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

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

func (RenderMode) String

func (i RenderMode) String() string

type ScriptBlock

type ScriptBlock struct {
	ast.BaseBlock
}

ScriptBlock marks where the Mermaid Javascript will be included.

This is a placeholder and does not contain anything.

func (*ScriptBlock) Dump

func (b *ScriptBlock) Dump(src []byte, level int)

Dump dumps the contents of this block to stdout.

func (*ScriptBlock) IsRaw

func (*ScriptBlock) IsRaw() bool

IsRaw reports that this block should be rendered as-is.

func (*ScriptBlock) Kind

func (*ScriptBlock) Kind() ast.NodeKind

Kind reports that this is a MermaidScriptBlock.

type ServerRenderer

type ServerRenderer struct {
	// MMDC is the MermaidJS CLI that we'll use
	// to render Mermaid diagrams server-side.
	//
	// Uses CLI by default.
	MMDC MMDC

	// ContainerTag is the name of the HTML tag to use for the container
	// that holds the Mermaid diagram.
	// The name must be without the angle brackets.
	//
	// Defaults to "div".
	ContainerTag string

	// Theme for mermaid diagrams.
	//
	// Values include "dark", "default", "forest", and "neutral".
	// See MermaidJS documentation for a full list.
	Theme string
}

ServerRenderer renders Mermaid diagrams into images server-side.

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

func (*ServerRenderer) RegisterFuncs

func (r *ServerRenderer) RegisterFuncs(reg renderer.NodeRendererFuncRegisterer)

RegisterFuncs registers the renderer for Mermaid blocks with the provided Goldmark Registerer.

func (*ServerRenderer) Render

func (r *ServerRenderer) Render(w util.BufWriter, src []byte, node ast.Node, entering bool) (ast.WalkStatus, error)

Render renders Block nodes.

type Transformer

type Transformer struct {
	// Don't add a ScriptBlock to the end of the page
	// even if the page doesn't already have one.
	NoScript bool
}

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

func (*Transformer) Transform

func (t *Transformer) Transform(doc *ast.Document, reader text.Reader, _ parser.Context)

Transform transforms the provided Markdown AST.