Diagramas Mermaid en GitHub y GitLab

La sintaxis

En cualquier archivo Markdown, abre un bloque de código con tres comillas invertidas seguidas de mermaid, pega el diagrama y cierra el bloque:

```mermaid
flowchart LR
  A[Push] --> B[Tests de CI] --> C{¿Pasan?}
  C -->|Sí| D[Desplegar]
  C -->|No| E[Avisar al autor]
```

GitHub muestra los bloques Mermaid desde febrero de 2022 en archivos Markdown, issues, pull requests, discusiones y wikis. GitLab los muestra en el Markdown de todo el producto, incluidas las merge requests y las wikis.

Dónde es más útil

• README: mostrar cómo funciona el servicio, o el flujo principal del usuario, en la propia página del repositorio.
• Registros de decisiones de arquitectura: comparar el flujo actual y el propuesto.
• Pull requests: ilustrar un cambio en un proceso o en un flujo de integración de API junto al código que lo implementa.
• Issues: describir un error como el camino que lleva a él.

Mantener los diagramas al día

Como el diagrama es texto dentro del repositorio, se puede revisar y cambiar en la misma pull request que el código. Una regla útil: si una pull request cambia un flujo, también actualiza el diagrama.

Solución de problemas

• Se ve el código en vez del diagrama: comprueba que el lenguaje del bloque es exactamente mermaid y que el bloque está bien cerrado.
• Aparece un error en vez del diagrama: un problema de sintaxis, a menudo paréntesis sin comillas o la palabra «end»; consulta la chuleta de sintaxis.
• Se ve distinto que en tu editor: cada plataforma incluye su propia versión de Mermaid, y puede que no tenga las funciones más recientes. Usa la sintaxis básica para que sea portable.
• Un diagrama muy grande se vuelve ilegible: divídelo en varios.

Mejor generarlo que escribirlo

Para un proceso descrito con palabras, puedes generar el diagrama con Flowchartio, exportarlo a Mermaid (.mmd) y pegar el contenido del archivo en el bloque de código. Los carriles se exportan como subgrafos, explicados en subgrafos y estilos.

Otros sitios donde Mermaid se muestra de forma nativa se tratan en Mermaid en Notion, Obsidian y herramientas de documentación.