Skip to content

Declarative Diagramming

Modern tools that turn text to diagrams. Community list of comparisons between Text to Diagram tools

Diagram Languages

D2 D2 Logo

D2: Declarative Diagramming - A modern language that turns text to diagrams.

Graphviz

Graphviz is open source graph visualization software. Graph visualization is a way of representing structural information as diagrams of abstract graphs and networks

Mermaid Mermaid Logo

Mermaid is a JavaScript based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically.

PlantUML PlantUML Logo

PlantUML is an open-source tool allowing users to create diagrams from a plain text language. Besides various UML diagrams, PlantUML has support for various other software development related formats (such as Archimate, Block diagram, BPMN, C4, Computer network diagram, ERD, Gantt chart, Mind map, and WBD), as well as visualisation of JSON and YAML files.

Ashley’s PlantUML DocumentationWikipedia

Plugin markdown-it-plantuml

Plugin for creating block-level uml diagrams for markdown-it markdown parser.

How does it work?

With this plugin you can create uml diagrams inside your markdown files

ts
@startuml
Bob -> Alice : hello
@enduml

or alternatively

```plantuml
bob -> Alice : hello
```

config.ts

ts
extendsMarkdown: (md) => {
    // regular @startuml opener
    md.use(require("markdown-it-plantuml"), {});
    // custom opener (hightlights code even in md editor)
    md.use(require('markdown-it-plantuml'), {
        openMarker: '```plantuml',
        closeMarker: '```',
        diagramName: 'uml',
        imageFormat: 'svg',
    });
},

that will be rendered as a svg image:

uml diagram

CDS Data Model

The Data Model comprises the description of the different entities involved in a business scenario.

It distinguishes between:

TypeDescription
Main business entitiesCompositions
are used to model document structures through “contained-in” relationships, also supporting Cascaded Delete.
Secondary business entitiesAssociations
uml diagram
ts
@startuml
' theming
skinparam shadowing false
skinparam ArrowColor #black
skinparam linetype ortho
' main business entities
rectangle Travel #lightskyblue
rectangle Booking #lightskyblue
' secondary business entities
rectangle Customer #white
rectangle Agency #white
rectangle Flight #white
' associations (control alignment with - (inline) or -- (next level))
Customer <-- Travel
Customer <-- Booking
Booking -> Travel
Travel --> Agency
Booking --> Flight
' legend
legend center
|  <#lightskyblue>  | Main business entitites |
|  <#white>  | Secondary business entities |
endlegend
@enduml

SAP Business Technology Platform Solution Diagram

Plantuml does not fully allow to control diagram style as defined in Solution Diagrams & Icons Guidelines PowerPoint Slide, but can be used for a first rough technology overview.

uml diagram
ts
@startuml
left to right direction
' theming
skinparam RoundCorner 0
skinparam DefaultTextAlignment center
skinparam rectangle {
    FontSize 22
    FontStyle bold
    BorderColor #0A6ED1
    BackgroundColor transparent
}
skinparam card<<srv>> {
    BorderThickness 0
    BackgroundColor transparent
    FontColor #074d92
    FontStyle bold
    StereotypeFontColor transparent
    StereotypeFontSize 1
}
skinparam card<<txt>> {
    BorderThickness 0
    BackgroundColor transparent    
    FontSize 48
    FontColor #7F7F7F
    StereotypeFontColor transparent
    StereotypeFontSize 1    
}
skinparam Arrow {
    Color #595959
}
' nodes
actor User as user
rectangle "SAP Business Technology Platform" as btp {    
    card "<img:https://domain/icons/btp/cloud-foundry-runtime.svg>\nApp Router" 
        as approuter <<srv>> 
    card "<img:https://domain/icons/btp/platform-identity-provider.svg>\nIdentity\nAuthentication\nServices" 
        as ias <<srv>> 
    card "<img:https://domain/icons/btp/destination.svg>\nDestination" 
        as destination <<srv>> 
    card "<img:https://domain/icons/btp/connectivity-service.svg>\nConnectivity" 
        as connectivity <<srv>> 
    card "<img:https://domain/icons/btp/html5-application-repository-service.svg>\nHTML5\nApp Repository" 
        as html5 <<srv>> 
    card "<img:https://domain/icons/btp/ui-theme-designer.svg>\nUI Theme\nDesigner" 
        as theme <<srv>> 
    rectangle "SAP Customer\nData Platform" as cdp #line.dashed {    
        card "<img:https://domain/icons/btp/platform-identity-provider.svg>\nIdentity\nProvider" as idp <<srv>> 
    }
}
rectangle "OnPremise" {
    card "<img:https://domain/icons/logo/sap-s4hana-text.png{scale=0.25}>\n<&home>" 
        as s4h <<txt>>
    card "<img:https://domain/icons/btp/cloudconnector.svg>\nCloud\n Connector" 
        as cc <<srv>> 
}
' associations
user --> approuter
approuter --> ias : <<JWT>>
ias --> idp : trust
approuter --> html5
html5 --> theme
approuter --> destination
destination --> connectivity
connectivity --> cc : Secure tunnel
cc -> s4h
@enduml

ditaa Diagrams

Plantuml supports ditaa (Diagrams Through Ascii Art). Tools like Textik or asciiflow simplify the creation of block graphics.

Maybe you will run into issues

As you can see in the next diagram, ditaa somethimes behaves with unexpected layout issues.

(-r,-S)
txt
+----------------------------+ +------------------------------------------------------+ +----------------------------+
|Protocols                   | |Frontends                                             | |Platform Services           |
|                            | |                                                      | |                            |
|                            | | +---------+ +---------+ +--------+ +------+ +------+ | |                            |
|                            | | |UI5/Fiori| |Analytics| |Workflow| |Mobile| |LC/NC | | | +------------------------+ |
|                            | | +---------+ +---------+ +--------+ +------+ +------+ | | |  Deployment & Binding  | |
| +------------------------+ | +------------------------------------------------------+ | +------------------------+ |
| | Cloud Events, AsyncAPI | |                                                          |                            |
| +------------------------+ | +------------------------------------------------------+ | +------------------------+ |
|                            | |CAP    +---+                             +---+        | | |    SaaS Management     | |
| +------------------------+ | |       |   | +-------------------------+ | C |        | | +------------------------+ |
| |    WebHooks, AMQP      | | |       | A | |                         | | O |        | |                            |
| +------------------------+ | |       | D | |  Enterprise Services    | | N |        | | +------------------------+ |
|                            | |       | A | |                         | | N |        | | |    Identity & Auth     | |
| +------------------------+ | |       | P | +-------------------------+ | E |        | | +------------------------+ |
| |     REST, OpenAPI      | o--------o| T |                             | C |o---------o                            |
| +------------------------+ | |       | O | +-------------------------+ | T |        | | +------------------------+ |
|                            | |       | R | |                         | | O |        | | |       Messaging        | |
| +------------------------+ | |       | S | |   Core Data Services    | | R |        | | +------------------------+ |
| |         OData          | | |       |   | |                         | | S |        | |                            |
| +------------------------+ | |       |   | +-------------------------+ |   |        | | +------------------------+ |
|                            | |       +---+                             +---+        | | |       Databases        | |
| +------------------------+ | +------------------------------------------------------+ | +------------------------+ |
| |        GraphQL         | |                                                          |                            |
| +------------------------+ | +------------------------------------------------------+ | +------------------------+ |
|                            | |Runtimes                                              | | |  Monitoring, Tracing   | |
|                            | |                                                      | | +------------------------+ |
|                            | | +----------+ +----------+ +----------+ +----------+  | |                            |
|                            | | |   Java   | |  Spring  | | Node.js  | |    TS    |  | |                            |
|                            | | +----------+ +----------+ +----------+ +----------+  | |                            |
+----------------------------+ +------------------------------------------------------+ +----------------------------+

Sequence Diagram

Used to draw a message between two participants.

uml diagram
ts
@startuml
skinparam sequence {
    ArrowColor #262f38
    DefaultFontColor #262f38
    LifeLineBorderColor #d67a65
}

actor User as User

box "Front-End Server\nNW AS ABAP 7.5 SP1 [GWD100]" #LightBlue  
    collections "UI5_UI5" as UI5_UI5 
	boundary  "Model Provider" as ODATA        
end box

note over UI5_UI5 
    ZAPP_GW (Package)
    ZGUI5 (UI5 BSP)
end note

box "Back-End Server\nNW AS ABAP 7.31 SP18 [ERP000]" #LightYellow
    boundary "Data Provider" as DPC_MPC
    control "Business Logic (BAPI)" as RUNTIME    
    database "Database" as DB
end box

note over DPC_MPC    
    ZAPP_GW (Package)
    ZAPP (SEGW Project)        
    ZCL_ZAPP_DPC_EXT (Classes)
end note

note over RUNTIME 
    ZAPP (Package)
    ZAPP (Function Group)
end note

note over DB 
    ZRW_CR (Table)
end note

group UI
    User -> UI5_UI5 : GET app request \n (index.html, *.css, *.js)
    User <- UI5_UI5 : MIME response
end

group ODATA [/sap/opu/odata/sap/ZAPP_SRV] 
    group GET Metadata [./$metadata]
        User -> ODATA : GET request        
        ODATA -> DPC_MPC : get service metadata
        ODATA <- DPC_MPC : metadata return
        User <- ODATA : XML response
    end
    
    group GET ChangeSet [./ChangeSet]
        User -> ODATA : GET request
        ODATA -> DPC_MPC : CHANGESET_GET_ENTITYSET
        DPC_MPC -> RUNTIME : call function Z_CHANGE_LIST_ZENTRAL 
        RUNTIME -> DB : SELECT * FROM ZRW_CR
        RUNTIME <- DB : data response
        DPC_MPC <- RUNTIME : function return
        ODATA <- DPC_MPC : deep structure return
        User -> ODATA : JSON response    
    end
    
    group GET Change [./ChangeSet('1234')?$expand=to_Items]
        User -> ODATA : GET request
        ODATA -> DPC_MPC : GET_EXPANDED_ENTITY
        DPC_MPC -> RUNTIME : call function Z_CHANGE_READ 
        RUNTIME -> DB : SELECT * FROM ZRW_CR
        RUNTIME <- DB : data response
        DPC_MPC <- RUNTIME : function return
        ODATA <- DPC_MPC : deep structure return
        User -> ODATA : JSON response    
    end
end
@enduml

VS Code Preview Extensions

Extensions can contribute custom styles and scripts to the Markdown preview to change its appearance and add new functionality.

Mermaid

Markdown Preview Mermaid Support adds Mermaid preview support.

Also interactively used by SAP CAP

```mermaid
flowchart LR
    hello
    w[world]

    hello -->|there| w
```

PlantUML

Markdown Plantuml Preview adds PlantUML preview support.

uml diagram
```plantuml
@startuml
[hello]
[world] as w

[hello] -> w: there
@enduml
```

D2

d2-markdown-preview adds D2 preview support.

```d2 layout=elk theme=101
hello
w: world

direction: right
hello -> w: there
```

Graphviz

Graphviz Markdown Preview adds GraphViz preview support.

Extension currently has some refresh issues that forces reopen preview.

```graphviz
digraph G {
  rankdir = "LR"
  hello
  w [label="world"]

  hello -> w [label="there"]
}
```

The following file contains a markdown example using all extensions:

VSCodePreviewDemo.md
# VS Code Markdown preview extensions

## Mermaid
```mermaid
flowchart LR
    hello
    w[world]

    hello -->|there| w
```

## PlantUML
```plantuml
@startuml
[hello]
[world] as w

[hello] -> w: there
@enduml
```

## D2
```d2 layout=elk theme=200
hello
w: world

direction: right
hello -> w: there
```

## Graphviz 
```graphviz
digraph G {
  rankdir = "LR"
  hello
  w [label="world"]

  hello -> w [label="there"]
}
```