Cómo controlar la disposición de los diagramas en Mermaid

En Mermaid 12, la clave de configuración layout determina el motor de disposición: ELK es el predeterminado para la mayoría de los diagramas de grafos, y para recuperar el motor anterior hay que establecer layout: dagre en el front matter o en mermaid.initialize().

Actualizaste la versión, volviste a compilar el sitio de documentación y un diagrama de flujo que nadie ha tocado ahora tiene otra forma y otros colores. Una sección de configuración por tipo de diagrama como flowchart: { defaultRenderer: ... }, sacada de una respuesta antigua, no lo va a solucionar.

Este artículo explica qué cambió, dónde configurar la disposición, qué ajuste tiene prioridad, cómo ajustar ELK y por qué una reversión puede parecer que no hace nada. Para los fundamentos de los diagramas de flujo, consulta creación de diagramas de flujo para flujos de trabajo.

¿Qué cambió en Mermaid 12?

A partir de Mermaid 12, un diagrama que no especifica una disposición se organiza con ELK en lugar de dagre. Eso significa que un diagrama sin cambios puede adoptar una forma distinta tras la actualización. La página de configuración de Layouts enumera siete tipos de diagrama que ahora usan ELK de forma predeterminada: flowchart, state, class, entidad-relación, requirement, use case y agentflow. ELK se distribuye con el paquete principal y se registra automáticamente. Los mindmaps siguen usando cose-bilkent de forma predeterminada, y tidy-tree proviene del paquete independiente @mermaid-js/layout-tidy-tree.

Las notas de la versión mermaid@12.0.0 también describen un segundo cambio. El tema predeterminado ahora es redux-color y el aspecto (look) predeterminado ahora es neo, para el conjunto más amplio de tipos de diagrama que figura en los valores predeterminados por diagrama de la página de temas. Así que un diagrama en la v12 puede verse distinto por dos motivos independientes: cambió el motor de disposición, y cambiaron el tema y el aspecto.

¿Dónde se configura la disposición: front matter, initialize() o configuración por tipo?

Puedes configurar la disposición de Mermaid en un único diagrama o para todos los diagramas de un sitio. También puedes limitar el tema y el aspecto a un solo tipo de diagrama. Cuando hay ajustes en conflicto, prevalece el más específico.

Las notas de la versión 12.0.0 indican este orden de resolución: primero el front matter o la directiva, luego initialize(), después el valor predeterminado del tipo de diagrama y, por último, el valor predeterminado global.

Así se revierte por completo un único diagrama:

---
config:
  layout: dagre
  theme: default
  look: classic
---
flowchart LR
  Request --> Auth{Valid token?}
  Auth -->|yes| Handler
  Auth -->|no| Reject

A nivel de sitio, la primera llamada que aparece a continuación cambia el motor y nada más, de modo que se mantienen los nuevos colores. La segunda llamada recupera todo el renderizado previo a la versión 12:

mermaid.initialize({ layout: 'dagre' });

mermaid.initialize({ layout: 'dagre', theme: 'default', look: 'classic' });

Mermaid 12 también permite limitar theme, look y layout a un tipo de diagrama, dentro de la sección de configuración de ese tipo. Un valor con ámbito prevalece sobre uno global definido en el mismo lugar. Para cambiar todos los diagramas a dagre pero recuperar la apariencia anterior solo en los diagramas de clases, mantén layout en el nivel superior y coloca theme y look en la sección class, tal como muestra la página de diagramas de clases:

mermaid.initialize({
  layout: 'dagre',
  class: { theme: 'default', look: 'classic' },
});

El front matter siempre prevalece sobre mermaid.initialize(). Supongamos que un sitio establece layout: 'dagre' a nivel global y un diagrama declara layout: elk en su front matter. Ese diagrama se renderiza con ELK.

¿Cuándo resulta útil la disposición ELK de Mermaid y cómo se ajusta?

Usa ELK para diagramas grandes o saturados. Quédate con dagre cuando un diagrama pequeño ya se ve bien. La documentación de Mermaid presenta ELK como la opción para grafos grandes y complejos, y dagre sigue disponible como la disposición por capas de toda la vida. Si tus diagramas se renderizaban bien antes de la actualización, volver a dagre es una opción razonable.

La sección de disposición de la referencia de sintaxis documenta varias claves de ajuste de ELK, entre ellas las siguientes. mergeEdges combina aristas paralelas. nodePlacementStrategy acepta SIMPLE, NETWORK_SIMPLEX, LINEAR_SEGMENTS o BRANDES_KOEPF, y BRANDES_KOEPF es el valor predeterminado con el preset default. nodePlacementAlignment define la alineación de Brandes-Koepf (por ejemplo, BALANCED o NONE). Si la omites, la alineación la determina el preset.

---
config:
  layout: elk
  elk:
    mergeEdges: true
    nodePlacementStrategy: NETWORK_SIMPLEX
---
flowchart TD
  Build --> Test --> Deploy
  Build --> Lint --> Deploy

Los diagramas que ya usaban ELK antes de la v12 también pueden cambiar, porque la colocación balanceada de Brandes-Koepf es ahora la predeterminada. El esquema de presets de ELK enumera cuatro valores de preset: legacy, default, modelOrder y depthFirst. Describe depthFirst como el valor predeterminado anterior e indica que legacy reproduce cómo renderizaba ELK antes de que existieran los presets.

La salida de ELK también ha cambiado dentro de la serie 12.x:

• Mermaid 12.1.0 añadió orientFeedbackEdges, que está activado de forma predeterminada. Una arista que va desde un nodo alimentado por un subgrafo de vuelta a ese mismo subgrafo ahora se enruta aguas abajo en lugar de rodear el subgrafo.
• Mermaid 12.2.0 hizo que ELK dejara de enderezar el extremo de una arista cuando hacerlo colocaría una etiqueta sobre otra arista.

config:
  layout: elk
  elk:
    preset: legacy
    orientFeedbackEdges: false

¿Qué variantes de ELK y algoritmos por subgrafo se pueden usar?

Además de layout: elk, la página de Layouts de Mermaid enumera seis variantes de ELK que puedes usar como valores de layout: elk.stress, elk.force, elk.mrtree, elk.sporeOverlap, elk.box y elk.rectpacking.

---
config:
  layout: elk.mrtree
---
flowchart TD
  Root --> API
  Root --> Web
  API --> Workers

Según las notas de la versión 12.0.0, elk.box y elk.rectpacking colocan los nodos pero no enrutan las aristas, por lo que estas se dibujan como líneas rectas de centro a centro.

Un subgrafo concreto puede elegir su propio algoritmo con @{ algorithm: ... }. Las mismas notas de la versión indican que los valores admitidos son las seis variantes más elk.layered y elk.radial. También señalan dos cosas sobre esta anulación: Mermaid ignora los valores no compatibles mostrando una advertencia, y utiliza el algoritmo heredado siempre que haya aristas que crucen el límite del subgrafo.

¿Por qué no funciona mi corrección de la disposición?

La mayoría de las reversiones fallidas se deben a una de cinco causas. Revísalas en este orden:

1. Sigues configurando defaultRenderer. La página de sintaxis de diagramas de flujo indica que se eliminó de las secciones flowchart, class y state en la v12. Usa layout en su lugar.
2. Solo configuraste layout: dagre. El tema redux-color y el aspecto neo siguen activos. Configura las tres claves.
3. El front matter prevalece sobre tu initialize(). Elimina layout del front matter de ese diagrama.
4. Un nombre de disposición está mal escrito o no está registrado. Las notas de la versión indican que Mermaid recurre a dagre mostrando una advertencia en lugar de lanzar un error. Revisa la consola.
5. Estás usando la compilación tiny. Consulta la siguiente sección.

Abandonar defaultRenderer es un cambio de una sola línea:

// Before (removed in v12)
mermaid.initialize({ flowchart: { defaultRenderer: 'elk' } });

// After
mermaid.initialize({ layout: 'elk' });

Si tu plataforma de documentación todavía no ha migrado a la v12, es posible que estas claves sigan comportándose como antes. Consulta la documentación de la propia plataforma.

¿Por qué la compilación tiny recurre a dagre?

La compilación tiny de Mermaid no incluye ELK, por lo que cualquier diagrama que solicite ELK en ella se renderiza con dagre. El paquete @mermaid-js/layout-elk se sigue publicando para este caso. Sigue los pasos de registro de la sección ELK and the tiny build de la documentación de uso. En la compilación normal, las llamadas existentes a registerLayoutLoaders siguen funcionando, pero ya no son necesarias y puedes eliminarlas.

Conclusión

Un diagrama que cambió tras la actualización a Mermaid 12 casi siempre lo hizo por dos causas: el motor de disposición ELK y el nuevo tema y aspecto. Decide qué quieres recuperar. Si solo quieres las formas anteriores, configura layout: dagre. Para el renderizado completo previo a la versión 12, configura layout: dagre, theme: default y look: classic. Después, busca en tu configuración cualquier ajuste residual de defaultRenderer y cualquier front matter que anule tu elección a nivel de sitio.

Preguntas frecuentes

¿Sigue funcionando la palabra clave de diagrama flowchart-elk en Mermaid 12?

Sí. Las notas de la versión 12.0.0 de Mermaid indican que flowchart-elk sigue funcionando como palabra clave explícita de diagrama. Lo que cambió fue la opción defaultRenderer. Mermaid la ignora en lugar de rechazarla, por lo que una configuración que todavía la establezca no genera ningún error, pero tampoco tiene efecto. Un diagrama que dependía de un valor 'elk' en defaultRenderer de flowchart para obtener su disposición ELK debe usar layout: elk en su lugar.

¿Incluir ELK hace que Mermaid 12 pese más al cargarse?

Solo crece de forma apreciable la compilación de un único archivo. En las compilaciones ESM, ELK es un chunk independiente que solo se carga cuando un diagrama lo utiliza. Las notas de la versión 12.0.0 indican que la compilación IIFE, mermaid.min.js, incorpora ELK en línea y crece aproximadamente 500 kB comprimido con gzip. La compilación tiny no incluye ELK, mantiene el mismo tamaño y resuelve con dagre las solicitudes de disposición ELK.

¿Puedo configurar las opciones de ajuste de ELK a nivel de sitio en lugar de hacerlo en el front matter de cada diagrama?

Sí. elk es una propiedad de nivel superior en el esquema de configuración de Mermaid, así que puedes pasarla a mermaid.initialize() junto a layout; por ejemplo, layout: 'elk' con un objeto elk que contenga mergeEdges: true y nodePlacementStrategy: 'NETWORK_SIMPLEX'. Una directiva %%{init}%% admite el mismo objeto elk para un único diagrama. El front matter de un diagrama concreto sigue prevaleciendo sobre los valores definidos a nivel de sitio.