mdbook-d2's Introduction

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 --locked

Or to install from git:

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

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
```