#mdbook #markdown #commonmark #d2

bin+lib mdbook-d2

D2 diagram generator plugin for MdBook

4 releases

new 0.2.2 Mar 30, 2023
0.2.1 Feb 9, 2023
0.2.0 Feb 8, 2023
0.1.0 Dec 26, 2022

#346 in Text processing

28 downloads per month

MIT license

375 lines

D2 preprocessor for mdbook

codecov Continuous integration

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


Install with cargo:

cargo install mdbook-d2 --locked

Or to install from git:

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


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



Add this to your book.toml:


# 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

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


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


~681K SLoC