package mermaid

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

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

Index

Variables

var DefaultCLI = MMDC("")

DefaultCLI is a CLI implementation that invokes the "mmdc" CLI by searching $PATH for it. 

var Kind = ast.NewNodeKind("MermaidBlock")

Kind is the node kind of a Mermaid Block node. 

var ScriptKind = ast.NewNodeKind("MermaidScriptBlock")

ScriptKind is the node kind of a Mermaid ScriptBlock node.

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 interface {
	// CommandContext builds an exec.Cmd to run the MermaidJS CLI
	// with the provided arguments.
	//
	// The list of arguments DOES NOT include 'mmdc'.
	CommandContext(context.Context, ...string) *exec.Cmd
}

CLI provides access to the MermaidJS CLI. Use it with CLICompiler to override how the "mmdc" CLI is invoked.

func MMDC

func MMDC(path string) CLI

MMDC returns a CLI implementation that invokes the "mmdc" CLI with the provided path.

If path is empty, $PATH will be searched for "mmdc".

type CLICompiler

type CLICompiler struct {
	// CLI is the MermaidJS CLI that we'll use
	// to compile Mermaid diagrams into images.
	//
	// If unset, uses DefaultCLI.
	CLI CLI

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

CLICompiler compiles Mermaid diagrams into images by shell-executing the "mmdc" command.

Plug it into ServerRenderer to use it.

func (*CLICompiler) Compile

func (d *CLICompiler) Compile(ctx context.Context, req *CompileRequest) (_ *CompileResponse, err error)

Compile compiles the provided Mermaid diagram into an SVG.

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.
	MermaidURL 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 CompileRequest

type CompileRequest struct {
	// Source is the raw Mermaid diagram source.
	Source string
}

CompileRequest is a request to compile a Mermaid diagram.

type CompileResponse

type CompileResponse struct {
	// SVG holds the SVG diagram text
	// including the <svg>...</svg> tags.
	SVG string
}

CompileResponse is a response from compiling a Mermaid diagram.

type Compiler

type Compiler interface {
	Compile(context.Context, *CompileRequest) (*CompileResponse, error)
}

Compiler compiles Mermaid diagrams into images. It is used with ServerRenderer to render Mermaid diagrams server-side.

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

	// Compiler specifies how to compile Mermaid diagrams server-side.
	//
	// If specified, and render mode is not set to client-side,
	// this will be used to render diagrams.
	Compiler Compiler

	// CLI specifies how to invoke the Mermaid CLI
	// to compile Mermaid diagrams server-side.
	//
	// If specified, and render mode is not set to client-side,
	// this will be used to render diagrams.
	//
	// If both CLI and Compiler are specified, Compiler takes precedence.
	CLI CLI

	// URL of Mermaid Javascript to be included in the page
	// for client-side rendering.
	//
	// Ignored if NoScript is true or if we're rendering diagrams server-side.
	//
	// Defaults to the latest version available on cdn.jsdelivr.net.
	MermaidURL 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

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

func (*Extender) Extend

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

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

type RenderMode

type RenderMode int

RenderMode specifies which renderer the Extender should use. 

const (
	// RenderModeAuto picks the renderer automatically.
	//
	// If a server-side compiler or CLI is specified,
	// or 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 {
	// Compiler specifies how to compile Mermaid diagrams into images.
	//
	// If unspecified, this uses CLICompiler.
	Compiler Compiler

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

ServerRenderer renders Mermaid diagrams into images server-side.

By default, it uses CLICompiler to compile Mermaid diagrams. You can specify a different compiler with Compiler. For long-running processes, you should use the compiler provided by the mermaidcdp package.

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:

func (*Transformer) Transform

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

Transform transforms the provided Markdown AST.

Directories

mermaidcdp Package mermaidcdp implements a server-side compiler for Mermaid diagrams that uses a headless Chromium-based browser to render the diagrams.