Diagrams

jhDocs includes support for two popular frameworks for creating diagrams using simple ASCII text:

• GoAT diagrams
• Mermaid diagrams

Both frameworks take simple ASCII text as input and render a graphical diagram for that input, using inline SVG.

GoAT diagrams tend to be simpler, rendering as simple line drawings. These diagrams use the page’s text color, which helps them blend into the page organically, in both light and dark mode.

Mermaid diagrams can be more complex, rendering with a packaged theme. Because the Mermaid theming doesn’t support both light and dark mode at the same time (you have to explicitly pick one or the other), we wrap Mermaid diagrams in a container that displays the light mode background color. This ensures that these diagrams are legible in both light and dark mode.

To render a diagram using either framework, wrap the ASCII representation of the diagram as a code block:

• First, add 3 backticks followed by either the word goat or mermaid, depending on the type of diagram you’re rendering, on its own line, with no spaces between the backticks and framework name. This begins the code block.
• Then starting on the next line, add the ASCII text for the diagram. The diagram text can take as many lines as needed.
• Finally, add 3 backticks on their own line. This ends the code block.

Example: Tree diagram using GoAT

      .               .                .               .--- 1          .-- 1     / 1
     / \              |                |           .---+            .-+         +
    /   \         .---+---.         .--+--.        |   '--- 2      |   '-- 2   / \ 2
   +     +        |       |        |       |    ---+            ---+          +
  / \   / \     .-+-.   .-+-.     .+.     .+.      |   .--- 3      |   .-- 3   \ / 3
 /   \ /   \    |   |   |   |    |   |   |   |     '---+            '-+         +
 1   2 3   4    1   2   3   4    1   2   3   4         '--- 4          '-- 4     \ 4

Example: Flowchart using Mermaid

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

Example: Large nodes using GoAT

   .---.       .-.        .-.       .-.                                       .-.
   | A +----->| 1 +<---->| 2 |<----+ 4 +------------------.                  | 8 |
   '---'       '-'        '+'       '-'                    |                  '-'
                           |         ^                     |                   ^
                           v         |                     v                   |
                          .-.      .-+-.        .-.      .-+-.      .-.       .+.       .---.
                         | 3 +---->| B |<----->| 5 +---->| C +---->| 6 +---->| 7 |<---->| D |
                          '-'      '---'        '-'      '---'      '-'       '-'       '---'

Example: Class diagram using Mermaid

classDiagram
Class01 <|-- AveryLongClass : Cool
Class03 *-- Class04
Class05 o-- Class06
Class07 .. Class08
Class09 --> C2 : Where am i?
Class09 --* C3
Class09 --|> Class07
Class07 : equals()
Class07 : Object[] elementData
Class01 : size()
Class01 : int chimp
Class01 : int gorilla
Class08 <--> C2: Cool label

Example: Complex diagram using GoAT

+-------------------+                           ^                      .---.
|    A Box          |__.--.__    __.-->         |      .-.             |   |
|                   |        '--'               v     | * |<---        |   |
+-------------------+                                  '-'             |   |
                       Round                                       *---(-. |
  .-----------------.  .-------.    .----------.         .-------.     | | |
 |   Mixed Rounded  | |         |  / Diagonals  \        |   |   |     | | |
 | & Square Corners |  '--. .--'  /              \       |---+---|     '-)-'       .--------.
 '--+------------+-'  .--. |     '-------+--------'      |   |   |       |        / Search /
    |            |   |    | '---.        |               '-------'       |       '-+------'
    |<---------->|   |    |      |       v                Interior                 |     ^
    '           <---'      '----'   .-----------.              ---.     .---       v     |
 .------------------.  Diag line    | .-------. +---.              \   /           .     |
 |   if (a > b)     +---.      .--->| |       | |    | Curved line  \ /           / \    |
 |   obj->fcn()     |    \    /     | '-------' |<--'                +           /   \   |
 '------------------'     '--'      '--+--------'      .--. .--.     |  .-.     +Done?+-'
    .---+-----.                        |   ^           |\ | | /|  .--+ |   |     \   /
    |   |     | Join        \|/        |   | Curved    | \| |/ | |    \    |      \ /
    |   |     +---->  o    --o--        '-'  Vertical  '--' '--'  '--  '--'        +  .---.
 <--+---+-----'       |     /|\                                                    |  | 3 |
                      v                             not:line    'quotes'        .-'   '---'
  .-.             .---+--------.            /            A || B   *bold*       |        ^
 |   |           |   Not a dot  |      <---+---<--    A dash--is not a line    v        |
  '-'             '---------+--'          /           Nor/is this.            ---

Example: Gantt diagram using Mermaid

gantt
dateFormat  YYYY-MM-DD
title GANTT diagram using mermaid
excludes weekdays 2023-01-10

section A section
Completed task            :done,    des1, 2023-01-06,2023-01-08
Active task               :active,  des2, 2023-01-09, 3d
Future task               :         des3, after des2, 5d
Future task2              :         des4, after des3, 5d