mdBook Graphviz

Install

cargo install mdbook-graphviz

Install Graphviz

brew install graphviz

book.toml

[preprocessor.graphviz]
command = "mdbook-graphviz"
output-to-file = false # defaults to false, change to true to create SVG files instead of rendering them inline

Usage

Just dot is supported, but any of the other graphviz tools would be easy to add.

Mark A dot Code Block For Processing

Input

```dot process
digraph {
    "processed" -> "graph"
}
```

Output

<div class="mdbook-graphviz-output"><svg>...</svg></div>

The class attribute gives you the chance to apply a common style to all the output images (e.g. center all of them).

Rendered

dot Code Blocks Without The process Flag Are Ignored

Input

```dot
digraph {
    "processed" -> "graph"
}
```

Output

```dot
digraph {
    "processed" -> "graph"
}
```

Output To File

The default is to embed the SVG as HTML in the Markdown, however if this causes problems or if the actual files are needed you can disable this via the output-to-file flag:

[preprocessor.graphviz]
output-to-file = true

or

MDBOOK_preprocessor__graphviz__output_to_file="true" mdbook build

.gitignore

This .gitignore should cover the generated SVG files.

*.generated.svg

Link To Output File

When using output-to-file, links can be added to the images via the link-to-file flag:

[preprocessor.graphviz]
output-to-file = true
link-to-file = true

or

MDBOOK_preprocessor__graphviz__output_to_file="true" MDBOOK_preprocessor__graphviz__link_to_file="true" mdbook build

Embedding dot files

Sometimes you don't want to write dot code, but instead include it from a file:

```dot
{{#include path/to/file.dot}}
```

In this case, you might want to modify the order of preprocessors, so the include directives get resolved before it's passed to Graphviz.

In that case, make sure your [preprocessor.graphviz] section in the config orders itself after links:

[preprocessor.graphviz]
after = ["links"]

Overriding the info-string

Some tools prefer a specific annotation for dot/graphviz diagrams. For compatability with these tools mdbook-graphviz can support a custom value for marking diagrams it should process. This is via the info-string flag:

[preprocessor.graphviz]
info-string = "graphviz"

or

MDBOOK_preprocessor__graphviz__info_string="graphviz" mdbook build

More information about preprocessors and ordering can be found here.