Tip of the Week: Diagrams as Code

Dave Bunten (@d33bs) Research Data Engineer

November 27, 2022 November 25, 2024

Tip of the Week: Diagrams as Code

Diagrams can be a useful way to illuminate and communicate ideas. Free-form drawing or drag and drop tools are one common way to create diagrams. With this tip of the week we introduce another option: diagrams as code (DaC), or creating diagrams by using code.

TLDR (too long, didn’t read); Diagrams as code (DaC) tools provide an advantage for illustrating concepts by enabling quick visual positioning, source controllable input, portability (both for input and output formats), and open collaboration through reproducibility. Consider using Mermaid (as well as many other DaC tools) to assist your diagramming efforts which can be used directly, within in your markdown files, or Github commentary using code blocks (for example, ` ```mermaid `).

Example Mermaid Diagram as Code

flowchart LR
    a --> b
    b --> c
    c --> d1
    c --> d2

flowchart LR
    a --> b
    b --> c
    c --> d1
    c --> d2

The above shows an example mermaid flowchart code and its rendered output. The syntax is specific to mermaid and acts as a simple coding language to help you depict ideas. Mermaid also includes options for sequence, class, Gantt, and other diagram types. Mermaid provides a live editor which can be used to quickly draft and share content.

Mermaid Github Integration

Mermaid diagrams may be rendered directly from markdown (.md) and text communication content (like pull request or issue comments) within Github. See Github’s blog post on mermaid for more details covering this topic.

Mermaid Jupyter Notebook Integration

Mermaid diagrams can be rendered directly within Jupyter notebooks with a small amount of additional code and a rendering service. One way to render mermaid and other diagrams within notebooks is to use Kroki.io. See this example for an interactive demonstration.

Version Controlling Your Diagrams

graph LR
    subgraph Compose
      write[Write Diagram Code]
      render[Render Diagram]
    end
    subgraph Store[Save and Share]
      save[Upload Diagram]
    end
    write --> | create | render
    render --> | revise | write
    render --> | code and exports | save

Mermaid version control workflow example

Creating your diagrams with code means you can enable reproducible and collaborative work on version control systems (like git). Using git in this way allows you to reference and remix your diagrams as part of development. It also allows others to collaborate on diagrams together making modifications as needed.

Additional Resources

Please see the following the additional resources which are related to diagrams as code.

• PlantUML
• Vega
• Kroki.io