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.
- 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 | ✅ |
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:
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