UML en un repositorio: Mermaid
La exportación que más renuncia y compra lo único que las otras no pueden: un diagrama que vive junto al código y cambia en la misma pull request.
5 min de lecturaXMI 2.5.13 de 3
01The trade, stated plainly
Mermaid is the worst of the three export formats at carrying a model and the only one of them that solves the problem most documentation actually has. XMI carries the metamodel; .qea carries the metamodel and the layout; Mermaid carries roughly what fits in a paragraph of text - and renders in a README without a build step.
That is the whole argument, and it is a good one. A diagram exported as PNG into a wiki is wrong within a quarter and nobody notices, because nothing about changing the code obliges anyone to look at it. A diagram in docs/architecture.md shows up in a diff when its file is touched, and a reviewer who can read the change can see the diagram disagree with it.
02What Mermaid can and cannot draw
| Element | Notation | What it means |
|---|---|---|
| Class diagram | Good | Classes, members, visibility, all six relationship kinds and multiplicities. The closest match to UML in the whole syntax. |
| Sequence diagram | Good | Participants, sync and async messages, activations, and alt, opt, loop and par blocks. |
| State diagram | Good | States, transitions with guards, composite states and history. |
| ER diagram | Good | Crow's foot cardinality and attribute lists. A close match to the ER article. |
| Use case diagram | Partial | Actors and cases, but no first-class include or extend. |
| Component, deployment, timing | Absent | No syntax at all. A flowchart approximation is possible and is not the same diagram. |
What is lost even in the good rows is worth naming: stereotypes, notes, constraints, and every trace of layout. Mermaid lays out its own diagrams, so the arrangement you spent an hour on does not survive - and for a diagram that is going to be regenerated on every change, that is a feature rather than a loss.
03Making it stick
Export the views a developer would actually open, which is almost never all of them. One class diagram of the core domain and one sequence diagram of the flow that everybody debugs is a better repository than fourteen files nobody reads.
Commit the Mermaid, not a rendered image. GitHub, GitLab and most static site generators render fenced mermaid blocks directly. An image checked in beside the source is a second copy that will disagree with it.
Regenerate rather than hand-edit. The moment somebody fixes a class name in the Markdown instead of in the model, the export has stopped being an export and the two versions begin to drift - which is the failure mode keeping a model current is entirely about.
In one line each
- 01Mermaid carries the least of the three formats and is the only one that lives in a diff.
- 02Class, sequence, state and ER map well; component, deployment and timing have no syntax.
- 03Stereotypes, notes, constraints and layout are all lost - and losing layout is fine here.
- 04Export the two or three views developers consult, not the whole model.
- 05Commit the text, never a rendered image, and regenerate rather than hand-edit.
04Preguntas frecuentes
¿Qué diagramas UML soporta Mermaid?
Clases, secuencia, estados y casos de uso tienen equivalentes directos, y existe además un diagrama entidad-relación. Componentes, despliegue, tiempos, estructura compuesta y el resto no tienen sintaxis, así que un modelo que los contenga se exporta parcialmente o nada.
¿Por qué exportar a Mermaid si pierde detalle?
Porque es texto, y el texto va en el repositorio. Un diagrama Mermaid aparece en el diff de una pull request, se renderiza solo en GitHub y GitLab, y se revisa junto al cambio que describe, que es el único mecanismo que mantiene un diagrama verdadero de forma fiable.
¿Sustituye Mermaid a una herramienta de modelado?
No. Mermaid dibuja diagramas; una herramienta de modelado sostiene un modelo detrás de muchas vistas. Renombrar una clase en Mermaid es editar un fichero; renombrarla en el modelo actualiza todas las vistas que la muestran. Usa Mermaid para las vistas que deben vivir en el repositorio.
Lecturas relacionadas