Diagramas como código con Mermaid

0
4677
Diagrama de secuencia con mermaid

Mermaid es una herramienta de creación de diagramas basada en
JavaScript que proporciona una notación inspirada en Markdown y un renderizador para crear y modificar diagramas de forma dinámica.

0. Índice de contenidos.

1. Introducción.

Mantener los diagramas y la documentación actualizada cuesta mucho a los equipos de desarrollo y todos sabemos que la documentación se queda obsoleta muy rápidamente. No tener una buena documentación actualizada perjudica la productividad de los equipos y limita el aprendizaje organizativo, porque la transferencia de conocimiento depende completamente de las personas. La mejor manera de mantener la documentación actualizada es que está lo más cerca del código posible, siempre siendo preferible que sea el código el que se autodocumente; aunque un mínimo de documentación, acerca de como ejecutarlo, probarlo o interactuar con él en los distintos entornos, qué componentes lo implementan y la interacción entre ellos es estrictamente necesaria y si ésta viene acompañada de algún diagrama que permita entenderlo mejor.

Existen muchas herramientas para generar diagramas en base a código, pero lo bueno de Mermaid es que permite escribir el código para generar los diagramas en formato Markdown, integrado en los propios README.md de nuestros proyectos, lo más cercano al código que podemos tener. Esta ventaja junto con la disponibilidad de plugins para su integración en distintos IDEs hacen que podamos visualizar los diagramas y modificarlos en caliente desde nuestras propias herramientas de desarrollo. En este sentido se parece a PlantUML, pero no necesitamos tener un fichero específico para generar el diagrama,
se integra directamente en la sintaxis de markdown de nuestros README.md.

Adicionalmente está soportado de forma nativa por github, de tal modo que cualquier diagrama escrito como código en un repositorio de github dentro de un fichero de markdown será renderizado como un diagrama con una herramienta visual de interacción con el mismo dentro del propio navegador.

2. Entorno.

El tutorial está escrito usando el siguiente entorno:

  • Hardware: Portátil MacBook Pro 16′ (Apple M1 Pro, 32GB DDR4).
  • Sistema Operativo: Mac OS Ventura 13

3. Diagramas como código

Con mermaid podemos crear diagramas de tipo UML y de otros tipos:

  • Flowchart
  • SequenceDiagram
  • ClassDiagram
  • StateDiagram
  • Gantt
  • Gitgraph
  • Pie

El diagrama por excelencia es el diagrama de secuencia que tiene una sintaxis muy similar a la de otras herramientas de generación de diagramas como código

  ```mermaid
  sequenceDiagram
      Alice->>John: Hello John, how are you?
      John-->>Alice: Great!
      Alice->>John: See you later!
  ```

Generaría un diagrama como el siguiente:

Diagrama de secuencia con mermaid

A continuación un ejemplo de diagrama de estados:

  ```mermaid
  stateDiagram-v2
    [*] --> Still
    Still --> [*]
    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]
  ```

Generaría un diagrama como el siguiente:

Diagrama de estados con mermaid

No tiene más complicación que conocer un poco la sintaxis y dejarse guiar por los ejemplos que podemos consultar tanto en la documentación como en la herramienta online para hacer pruebas https://mermaid.live/

4. Integración en el IDE.

Al igual que con PlantUML existen plugins para nuestros IDEs favoritos que nos permiten integrar la renderización de los diagramas en nuestro markdown directamente en tiempo de desarrollo.

De este modo, trabajando con IntelliJ, podemos instalarlo fácilmente y comprobar qué tal pinta tendrá nuestro README.md.

Diagrama con mermaid en Intellij

La instalación es muy sencilla a través de los plugins del IDE y no requiere de ningún tipo de herramienta adicional instalada en el sistema operativo, como con PlanUML.

5. Integración en los repositorios de código.

Lo realmente interesante de mermaid es su integración nativa con github y gitlab que nos permite, desde el propio site de nuestro proyecto, accediendo a las páginas de markdown, visualizar los diagramas directamente en el navegador.

Diagrama con mermaid en github

Además de mostrar el diagrama en modo gráfico, proporciona un pequeño visualizador que permite movernos por el mismo, hacer zoom y exportar el diagrama en modo código.

6. Integración en chrome.

Si tienes la mala suerte de usar bitbucket, a día de hoy no existe un plugin de mermaid para el mismo. Hay una alternativa usando un plugin para integrar mermaid en el propio chrome; existen varios de hecho, que te permitirían renderizar como diagramas el lenguaje de marcado de mermaid de cualquier página aunque están pensados para suplir esa carencia en bitbucket.

Instalándote el plugin Mermaid Previewer en Chrome, el código del siguiente diagrama deberías verlo directamente con su representación gráfica en el navegador.


    sequenceDiagram
      Alice->>John: Hello John, how are you?
      John-->>Alice: Great!
      Alice->>John: See you later!
  

Solo tienes que adecuar el código al matcher del plugin, sin incluir la parte del markdown.

  <pre lang="mermaid">
    <code>
    sequenceDiagram
        Alice->>John: Hello John, how are you?
        John-->>Alice: Great!
        Alice->>John: See you later!
    </code>
  </pre>

Si no te queda otra…

7. Conclusiones.

En este tutorial hemos visto una alternativa muy interesante a PlantUML, que nos permite incluir directamente nuestros diagramas como código en los ficheros de markdown.

Quizás no es tan potente como PlantUML pero la integración dentro de nuestros README.md y su visualización directa en github, la hacen una alternativa muy atractiva para intentar mantener la documentación y los diagramas, lo más junto al código posible y lo más actualizados que podamos.

DEJA UNA RESPUESTA

Por favor ingrese su comentario!

He leído y acepto la política de privacidad

Por favor ingrese su nombre aquí

Información básica acerca de la protección de datos

  • Responsable:
  • Finalidad:
  • Legitimación:
  • Destinatarios:
  • Derechos:
  • Más información: Puedes ampliar información acerca de la protección de datos en el siguiente enlace:política de privacidad