Diagrams

Four diagram tools are supported by Doctopus: D2, Pikchr, Graphviz, and PlantUML. Choose the one that best suits your needs.

D2

Excels at developer productivity and readability, offering a modern, intuitive syntax and versatile layout engine support.

```d2
direction: down

start: Start {
  shape: oval
}

q1: Is graph layout the main problem? {
  shape: diamond
}

q2: Do you want procedural placement control? {
  shape: diamond
}

graphviz: Graphviz
pikchr: Pikchr
d2lang: D2

start -> q1
q1 -> graphviz: Yes
q1 -> q2: No
q2 -> pikchr: Yes
q2 -> d2lang: No
```

Pikchr

Excels at precise technical illustrations, providing a language optimized for relative positioning.

```pikchr
down

Start: oval "Start" fit
arrow

Q1: box invis width 2.6in height 1.0in "Is graph layout the" "main problem?"
line from Q1.w to Q1.n to Q1.e to Q1.s close

A1: arrow from Q1.e right 1.5in "Yes" above
GV: box "Graphviz" fit with .w at A1.end

A2: arrow from Q1.s down 1.0in "No" ljust
Q2: box invis width 3.0in height 1.0in "Do you want procedural" "placement control?" with .n at A2.end
line from Q2.w to Q2.n to Q2.e to Q2.s close

A3: arrow from Q2.e right 1.5in "Yes" above
PK: box "Pikchr" fit with .w at A3.end

A4: arrow from Q2.s down 1.0in "No" ljust
D2Lang: box "D2" fit with .n at A4.end
```

PlantUML

Excels at UML diagrams and architecture sketches, especially sequence, deployment, and entity-relationship diagrams.

By default, PlantUML support uses the plantuml command from your PATH. If plantuml is missing, rendering a plantuml or puml code block fails.

You can configure tools.plantuml to use a PlantUML server, a PlantUML JAR, or a specific PlantUML binary. If a server is configured, Doctopus uses that server and does not try the local CLI.

If you are fine with using a remote PlantUML rendering service, you can add it to your configuration. https://www.plantuml.com/plantuml is the official one. You can self-host one as well.

```plantuml
@startuml
actor User
participant Doctopus
participant Cache
participant "PlantUML" as PlantUML

User -> Doctopus: Build docs
Doctopus -> Cache: Check rendered SVG

alt Cache hit
    Cache --> Doctopus: SVG
else Cache miss
    Cache --> Doctopus: Not found
    Doctopus -> PlantUML: Render SVG
    PlantUML --> Doctopus: SVG
    Doctopus -> Cache: Store SVG
end

Doctopus --> User: Static site
@enduml
```

Graphviz

Excels at automated large-scale graph layouts, utilizing mature, mathematically robust algorithms for complex relational data.

dot is the most commonly used tool in the Graphviz ecosystem. It is used by PlantUML under the hood.

```dot
digraph DecisionTree {
  rankdir=TB;
  node [shape=box];
  edge [];

  start [shape=oval, label="Start"];
  q1 [shape=diamond, label="Is graph layout\nthe main problem?"];
  q2 [shape=diamond, label="Do you want procedural\nplacement control?"];

  graphviz [label="Graphviz"];
  pikchr [label="Pikchr"];
  d2lang [label="D2"];

  start -> q1;
  q1 -> graphviz [xlabel="Yes"];
  q1 -> q2 [xlabel="No"];
  q2 -> pikchr [xlabel="Yes"];
  q2 -> d2lang [xlabel="No"];
}
```

You can also pick a different layout engine from the fence language, for example circo, fdp, neato, osage, patchwork, sfdp, or twopi.

```circo
digraph DecisionTree {
  rankdir=TB;
  node [shape=box];
  edge [];

  start [shape=oval, label="Start"];
  q1 [shape=diamond, label="Is graph layout\nthe main problem?"];
  q2 [shape=diamond, label="Do you want procedural\nplacement control?"];

  graphviz [label="Graphviz"];
  pikchr [label="Pikchr"];
  d2lang [label="D2"];

  start -> q1;
  q1 -> graphviz [xlabel="Yes"];
  q1 -> q2 [xlabel="No"];
  q2 -> pikchr [xlabel="Yes"];
  q2 -> d2lang [xlabel="No"];
}
```