D2 preprocessor for mdbook

A preprocessor for mdbook to convert d2 codeblocks into SVG images using D2.

Installation

Install with cargo:

cargo install mdbook-d2

Or to install from git:

cargo install --git https://github.com/danieleades/mdbook-d2

Requirements

This preprocessor assumes that D2 is installed locally and on the path. D2 installation instructions can be found here.

Check that the local installation is working correctly using

d2 --version

Usage

Configuration

Add this to your book.toml:

[preprocessor.d2]

# path to d2 binary.
# optional. default is "d2" (ie. on the path).
path = "d2"

# layout engine for diagrams. See https://github.com/terrastruct/d2#plugins.
# optional. default is "dagre".
layout = "dagre"

# whether to use inline svg when rendering.
# if 'false', separate files will be generated in src/<output-dir> and referenced.
# optional. default is 'true'
inline = true

# output directory relative to `src/` for generated diagrams.
# This is ignored if 'inline' is 'true'.
# optional. default is "d2".
output-dir = "d2"

Code Blocks

Use in your 'book' by annotating D2 code blocks-

## My Diagram

```d2
# Actors
hans: Hans Niemann

defendants: {
  mc: Magnus Carlsen
  playmagnus: Play Magnus Group
  chesscom: Chess.com
  naka: Hikaru Nakamura

  mc -> playmagnus: Owns majority
  playmagnus <-> chesscom: Merger talks
  chesscom -> naka: Sponsoring
}

# Accusations
hans -> defendants: 'sueing for $100M'

# Offense
defendants.naka -> hans: Accused of cheating on his stream
defendants.mc -> hans: Lost then withdrew with accusations
defendants.chesscom -> hans: 72 page report of cheating
```

The code block will be replaced with the D2 diagram in the rendered document.

Thanks

The code in this preprocessor is based on that from https://github.com/matthiasbeyer/mdbook-svgbob2