Mermaid.js

Mermaid is an innovative open-source tool for creating diagrams using a text-based syntax inspired by Markdown. Launched in 2014, it aims to simplify the creation and modification of diagrams while making them easier to share. Over time, Mermaid has expanded its capabilities to include various types of diagrams, such as flowcharts, sequence diagrams, and entity-relationship diagrams, addressing a wide range of documentation needs.  

Mermaid’s native integration into major platforms like GitHub, GitLab, and Notion, as well as its availability through extensions for Confluence, Google Docs, and VSCode, highlights its growing relevance. This integration elevates visual creation to the same level as textual documentation, promoting clearer and more effective communication. Mermaid’s intuitive syntax (e.g., A --> B) allows beginners to quickly create their first diagrams. The tool automatically optimizes layouts, enabling users to focus on content rather than formatting.  

Mermaid offers some flexibility in representation, such as using specific shapes for databases or dashed links. Styling is primarily limited to CSS-based coloring, which remains basic and somewhat difficult to master. However, more advanced customizations, such as adding images, adjusting canvas size, or including dynamic elements, remain out of reach.  

Theodo’s point of view  

We recommend adopting Mermaid in organizations that use tools supporting it natively. Its use should be encouraged among team members to effectively complement their usual documentation. However, for diagrams intended for an external audience or requiring extensive customization or complexity, other tools such as draw.io, Excalidraw, or Whimsical may be more suitable.