indoorvivants / mdoc-d2   0.0.1

Website GitHub

Mdoc plugin to render D2 diagrams in your markdown

Scala versions: 3.x 2.13 2.12

D2 diagrams in your Mdoc files

Mdoc is the tool for compiled documentation in Scala projects

D2 is a declarative diagram definition language

This project is a simple plugin for mdoc that allows you to embed D2 diagrams in your markdown files.

Installation

  • SBT: libraryDependencies += "com.indoorvivants" %% "mdoc-d2" % "0.0.1"
  • Mill: def ivyDeps = Agg(ivy"com.indoorvivants::mdoc-d2:0.0.1")
JVM
Scala 2.12
Scala 2.13
Scala 3

Usage

Note that Github intentionally doesn't render images which are specified using the data: source - it's done for security reasons, and as such you won't see the diagrams rendered on this page. Please refer to the website insteadh which hosts a copy of this documentation

You don't need to install D2, it will be bootstrapped by Yank.

Simple use the scala mdoc:d2 language in your markdown snippets and enjoy:

```scala mdoc:d2
direction:right
dogs -> cats -> mice: chase
replica 1 <-> replica 2
a -> b: To err is human, to moo bovine {
  source-arrowhead: 1
  target-arrowhead: * {
    shape: diamond
  }
}
```

will be rendered as an image:

You can also pass the parameters directly to D2 CLI tool, by using the special #! comments. For example, here we set layout to ELK and theme to 100:

```scala mdoc:d2
#!layout=elk
#!theme=100
direction:right
dogs -> cats -> mice: chase
replica 1 <-> replica 2
a -> b: To err is human, to moo bovine {
  source-arrowhead: 1
  target-arrowhead: * {
    shape: diamond
  }
}
```

will be rendered as an image:

Contributing

If you want to update this documentation file, don't edit it directly - edit docs/README.in.md and run sbt updateDocs. It's annoying, but this document contains compiled snippets of code which I want to prevent from going out of date