dot2svg

README

dot2svg

Render a Graphviz DOT graph to SVG — in pure Go, via go-mermaid. No Graphviz binary required.

Why

Plenty of tools emit DOT — terraform graph, go tool pprof -dot, make2graph, git log --graph-adjacent tooling — but rendering it has always meant shelling out to the native Graphviz dot binary. dot2svg skips that: it's a single static binary, or a library call.

This is not a Graphviz replacement. It covers a practical subset — digraph/graph, node and edge statements (including chains like A -> B -> C), default node [...]/edge [...] attributes, rankdir, and subgraphs/clusters — which is what the tools above actually emit. Record shapes, HTML-like labels, and Graphviz's own layout algorithm are out of scope; go-mermaid's Sugiyama layout lays the graph out instead, so the result won't be pixel-identical to dot.

Install

Library:

go get github.com/zkrebbekx/dot2svg

CLI:

go install github.com/zkrebbekx/dot2svg/cmd/dot2svg@latest

Homebrew:

brew install zkrebbekx/tap/dot2svg

Docker:

terraform graph | docker run -i --rm ghcr.io/zkrebbekx/dot2svg > graph.svg

Prebuilt binaries for Linux/macOS/Windows (amd64/arm64) are attached to each GitHub release.

Usage

dot2svg graph.dot > graph.svg
terraform graph | dot2svg > graph.svg
go tool pprof -dot ./mybinary cpu.prof | dot2svg -o profile.svg
dot2svg -format mmd -o graph.mmd graph.dot   # raw Mermaid source
dot2svg -format png -scale 2 -o graph.png graph.dot
dot2svg a.dot b.dot                          # batch: writes a.svg, b.svg

Library:

package main

import (
	"os"

	"github.com/zkrebbekx/dot2svg"
)

func main() {
	src, _ := os.ReadFile("graph.dot")
	svg, err := dot2svg.Render(src)
	if err != nil {
		panic(err)
	}
	os.WriteFile("graph.svg", svg, 0o644)
}

Render accepts the same functional options as go-mermaid.Render (theme, spacing, ...). dot2svg.ToMermaid(src) returns just the Mermaid flowchart text, without rendering it.

How it maps

DOT	diagram
digraph / graph	directed (-->) or undirected (---) edges
each node statement	a node — shape follows the closest Mermaid equivalent (see below)
rankdir	the Mermaid flowchart direction (TB/LR/RL/BT — same vocabulary as DOT)
label="..." (edge)	a pipe-delimited Mermaid edge label
subgraph / cluster	a Mermaid subgraph, titled by the subgraph's own label if set
node [...] / edge [...]	default attributes for statements that follow in the same block

Shape mapping: box/rect/unset → rectangle, ellipse/oval/note → rounded, circle/doublecircle → double-circle, diamond → diamond. Anything else falls back to a rectangle.

Node IDs in the diagram are short and sequential (n1, n2, ...) rather than derived from the DOT identifier — DOT IDs from tools like Terraform are often long, quoted resource addresses; the original text is kept as the node's label, not mangled into an identifier. Labels are sanitized of characters ([, ], (, ), {, }, |, ") that would otherwise be misread as Mermaid shape or edge-label delimiters, and Graphviz's \n/\l/\r line-break escapes collapse to spaces.

Develop

make test
make lint
make build

License

MIT

Documentation

Overview

Package dot2svg renders a practical subset of the Graphviz DOT language to SVG — in pure Go, via go-mermaid — for tools that emit DOT but don't want to depend on the native Graphviz binary: `terraform graph`, `go tool pprof -dot`, `make2graph`, and similar.

svg, err := dot2svg.Render(dotSource)

DOT is parsed into a graph model, translated into Mermaid flowchart source, and handed to mermaid.Render. Supported DOT: digraph/graph, node and edge statements (including A -> B -> C chains), default `node [...]`/`edge [...]` attributes, `rankdir`, and subgraphs/clusters (rendered as Mermaid subgraphs). This is deliberately not full Graphviz fidelity — record shapes, HTML-like labels, and Graphviz's own layout algorithm are out of scope; go-mermaid's Sugiyama layout lays the graph out instead, so the result won't be pixel-identical to `dot`.

Index

• func Render(src []byte, opts ...mermaid.Option) ([]byte, error)
• func ToMermaid(src []byte) (string, error)
• type Cluster
• type Edge
• type Graph
• type Node

Functions

func Render

func Render(src []byte, opts ...mermaid.Option) ([]byte, error)

Render parses a DOT source document and renders it straight to SVG via go-mermaid. opts are passed through to mermaid.Render (theme, padding, spacing, ...).

func ToMermaid

func ToMermaid(src []byte) (string, error)

ToMermaid parses a DOT source document and returns the equivalent Mermaid flowchart source.

Types

type Cluster

type Cluster struct {
	// ID is the subgraph's name as written (e.g. "cluster_0"), or a
	// generated "cluster1", "cluster2", ... for anonymous subgraphs.
	ID string
	// Title is the subgraph's `label` attribute if set, otherwise ID.
	Title string
}

Cluster is a subgraph that contains at least one node.

type Edge

type Edge struct {
	From, To string
	// Label is the edge's `label` attribute, if any.
	Label string
}

Edge is a directed or undirected relationship between two nodes.

type Graph

type Graph struct {
	// Directed is true for `digraph`, false for `graph`.
	Directed bool
	// RankDir is the graph's `rankdir` attribute (TB, LR, RL, BT),
	// defaulting to TB as Graphviz does.
	RankDir string

	Nodes    []Node
	Edges    []Edge
	Clusters []Cluster
}

Graph is the graph extracted from a DOT source. Nodes, Edges, and Clusters are in first-seen order.

type Node

type Node struct {
	// Key is the node's identifier as written (unescaped, but otherwise
	// verbatim — may contain spaces or punctuation if it was quoted).
	Key string
	// Label is the display text: the node's `label` attribute if set,
	// otherwise Key.
	Label string
	// Shape is the Graphviz `shape` attribute, lowercased; empty if unset.
	Shape string
	// Cluster is the ID of the subgraph this node was declared in; empty
	// if the node is at the top level.
	Cluster string
}

Node is one node declared in the DOT source.