🎄 Enhancing Developer Documentation and Websites with Mermaid.js 🌟

Dec 2, 2023

Back to 2023 Advent Calendar

Mermaid.js has revolutionized the way developers create diagrams, offering a text-based approach that integrates seamlessly into various documentation and web platforms.

If you haven't used MermaidJS this year, we highly recommend you to add that into your toolbox for next year.

2 primary use cases for using MermaidJS

1. Mermaid.js in Markdown Documentation

Traditional image-based diagrams, while useful, often become a hassle to update. With MermaidJS you can create and maintain diagrams directly within your Markdown files. e.g

graph TD
  messageClient --> |sendMessage|messageBackend
  messageBackend --> userService
  userService --> userDB[(userDB)]
  messageBackend --> messageDB
  messageDB[(messageDB)] -->|change data captrure|messageQueue
  messageQueue --> messageNotifier
  messageNotifier --> pushNotifications{{pushNotifications}}

When you change how your code interacts, you can just update diagram in the same PR.

2. Mermaid.js for Developer Websites

Visualizing complex systems like distributed networks is crucial for developers.

Mermaid.js offers a straightforward way to depict these systems, particularly useful for sites that require dynamic diagrammatic representations.

Example below is a diagram of a call trace, that can be created with a few lines of code.

graph TD
  apiGateway --> |34ms|usersService
  apiGateway --> |552ms|organizationService
  organizationService --> |540ms|organizationSearch
  apiGateway --> |220ms|repoService
  repoService --> |200ms|starGazerCache
  repoService --> |15ms|watchersCache