Como controlar o layout de diagramas no Mermaid

No Mermaid 12, a chave de configuração layout define o motor de layout: o ELK é o padrão para a maioria dos diagramas de grafo, e você define layout: dagre no front matter ou em mermaid.initialize() para voltar ao motor anterior.

Você atualizou, fez o rebuild do site de documentação, e um fluxograma que ninguém tocou agora tem um formato e cores diferentes. Uma seção de configuração por tipo de diagrama, como flowchart: { defaultRenderer: ... }, sugerida em alguma resposta antiga, não vai resolver o problema.

Este artigo aborda o que mudou, onde definir o layout, qual configuração tem prioridade, como ajustar o ELK e por que uma reversão pode parecer não ter efeito algum. Para o básico sobre fluxogramas, veja creating flowcharts for workflows.

O que mudou no Mermaid 12?

A partir do Mermaid 12, um diagrama que não especifica um layout é organizado pelo ELK em vez do dagre. Isso significa que um diagrama inalterado pode sair com um formato diferente depois da atualização. A página de configuração de Layouts lista sete tipos de diagrama que agora usam o ELK por padrão: fluxograma, estado, classe, entidade-relacionamento, requisitos, caso de uso e agentflow. O ELK vem incluído no pacote principal e se registra automaticamente. Os mindmaps continuam usando o cose-bilkent por padrão, e o tidy-tree vem do pacote separado @mermaid-js/layout-tidy-tree.

As release notes do mermaid@12.0.0 também descrevem uma segunda mudança. O tema padrão agora é o redux-color e o look padrão agora é o neo, para o conjunto mais amplo de tipos de diagrama listado nos padrões por diagrama da página de temas. Portanto, um diagrama na v12 pode ficar diferente por dois motivos distintos: o motor de layout mudou, e o tema e o look mudaram.

Onde definir o layout: front matter, initialize() ou configuração por tipo?

Você pode definir o layout do Mermaid em um único diagrama ou para todos os diagramas de um site. Também pode restringir o tema e o look a um único tipo de diagrama. Quando há conflito entre configurações, a mais específica prevalece.

As release notes da 12.0.0 apresentam a ordem de resolução assim: primeiro o front matter ou a diretiva, depois initialize(), em seguida o padrão do tipo de diagrama e, por fim, o padrão global.

Veja como reverter completamente um único diagrama:

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

Para o site inteiro, a primeira chamada abaixo altera apenas o motor, então as novas cores permanecem. A segunda chamada traz de volta toda a renderização anterior à versão 12:

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

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

O Mermaid 12 também permite restringir theme, look e layout a um tipo de diagrama, dentro da seção de configuração desse tipo. Um valor com escopo prevalece sobre um valor global definido no mesmo lugar. Para mudar todos os diagramas para o dagre, mas restaurar a aparência antiga apenas nos diagramas de classe, mantenha layout no nível superior e coloque theme e look na seção class, como mostra a página de diagramas de classe:

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

O front matter sempre prevalece sobre mermaid.initialize(). Suponha que um site defina layout: 'dagre' para todo o site e que um diagrama declare layout: elk no seu front matter. Esse diagrama será renderizado com o ELK.

Quando o layout ELK do Mermaid ajuda e como ajustá-lo?

Use o ELK para diagramas grandes ou carregados. Mantenha o dagre quando um diagrama pequeno já estiver com boa aparência. A documentação do Mermaid recomenda o ELK para grafos grandes e complexos, e o dagre continua disponível como o tradicional layout em camadas. Se seus diagramas eram bem renderizados antes da atualização, reverter para o dagre é uma escolha razoável.

A seção de layout da referência de sintaxe documenta várias chaves de ajuste do ELK, incluindo as seguintes. mergeEdges combina arestas paralelas. nodePlacementStrategy aceita SIMPLE, NETWORK_SIMPLEX, LINEAR_SEGMENTS ou BRANDES_KOEPF, sendo BRANDES_KOEPF o padrão no preset default. nodePlacementAlignment define o alinhamento do Brandes-Koepf (por exemplo, BALANCED ou NONE). Quando omitido, o alinhamento vem do preset.

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

Diagramas que já usavam o ELK antes da v12 também podem mudar, porque o posicionamento Brandes-Koepf balanceado agora é o padrão. O schema de preset do ELK lista quatro valores de preset: legacy, default, modelOrder e depthFirst. Ele descreve depthFirst como o padrão anterior e informa que legacy reproduz a forma como o ELK renderizava antes da existência dos presets.

A saída do ELK também mudou ao longo da 12.x:

• O Mermaid 12.1.0 adicionou orientFeedbackEdges, que vem ativado por padrão. Uma aresta que parte de um nó alimentado por um subgrafo e volta para esse mesmo subgrafo agora é roteada no sentido do fluxo, em vez de contornar o subgrafo.
• O Mermaid 12.2.0 fez o ELK deixar de endireitar a extremidade de uma aresta quando isso colocaria um rótulo sobre outra aresta.

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

Quais variantes do ELK e algoritmos por subgrafo você pode usar?

Além de layout: elk, a página de Layouts do Mermaid lista seis variantes do ELK que você pode usar como valores de layout: elk.stress, elk.force, elk.mrtree, elk.sporeOverlap, elk.box e elk.rectpacking.

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

De acordo com as release notes da 12.0.0, elk.box e elk.rectpacking posicionam os nós, mas não roteiam as arestas, então elas são desenhadas como linhas retas de centro a centro.

Um único subgrafo pode escolher seu próprio algoritmo com @{ algorithm: ... }. As mesmas release notes listam como valores aceitos as seis variantes, além de elk.layered e elk.radial. Elas também informam duas coisas sobre essa sobrescrita: o Mermaid ignora valores não suportados, emitindo um aviso, e usa o algoritmo herdado sempre que arestas cruzam o limite do subgrafo.

Por que minha correção de layout não está funcionando?

A maioria das reversões que falham tem uma de cinco causas. Verifique-as nesta ordem:

1. Você ainda define defaultRenderer. A página de sintaxe de fluxogramas informa que ele foi removido das seções flowchart, class e state na v12. Use layout no lugar.
2. Você definiu apenas layout: dagre. O tema redux-color e o look neo continuam ativos. Defina as três chaves.
3. O front matter sobrescreve seu initialize(). Remova layout do front matter desse diagrama.
4. O nome de um layout está escrito errado ou não foi registrado. As release notes informam que o Mermaid faz fallback para o dagre com um aviso, em vez de lançar um erro. Verifique o console.
5. Você está usando o build tiny. Veja a próxima seção.

Abandonar o defaultRenderer é uma mudança de uma linha:

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

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

Se a sua plataforma de documentação ainda não migrou para a v12, essas chaves podem continuar se comportando da forma antiga. Consulte a documentação da própria plataforma.

Por que o build tiny faz fallback para o dagre?

O build tiny do Mermaid não inclui o ELK, então qualquer diagrama que solicite o ELK nele é renderizado com o dagre. O pacote @mermaid-js/layout-elk continua sendo publicado para esse caso. Siga as etapas de registro na seção ELK and the tiny build da documentação de uso. No build normal, chamadas existentes a registerLayoutLoaders continuam funcionando, mas não são mais necessárias, e você pode removê-las.

Conclusão

Um diagrama que mudou após a atualização para o Mermaid 12 quase sempre tem duas causas: o motor de layout ELK e o novo tema e look. Decida o que você quer recuperar. Se quiser apenas os formatos antigos, defina layout: dagre. Para a renderização completa anterior à versão 12, defina layout: dagre, theme: default e look: classic. Em seguida, procure na sua configuração qualquer defaultRenderer remanescente e qualquer front matter que sobrescreva a escolha feita para o site inteiro.

Perguntas frequentes

A palavra-chave de diagrama flowchart-elk ainda funciona no Mermaid 12?

Sim. As release notes do Mermaid 12.0.0 informam que flowchart-elk continua funcionando como palavra-chave explícita de diagrama. O que mudou foi a opção defaultRenderer. O Mermaid a ignora em vez de rejeitá-la, então uma configuração que ainda a define não gera erro, mas também não tem efeito. Um diagrama que dependia de um defaultRenderer de flowchart com valor 'elk' para obter o layout ELK deve passar a definir layout: elk.

Incluir o ELK no pacote deixa o Mermaid 12 mais pesado para carregar?

Apenas o build de arquivo único cresce de forma perceptível. Nos builds ESM, o ELK é um chunk separado que só é carregado quando um diagrama o utiliza. As release notes da 12.0.0 informam que o build IIFE, mermaid.min.js, incorpora o ELK e cresce cerca de 500 kB com gzip. O build tiny não inclui o ELK, mantém o mesmo tamanho e organiza com o dagre os diagramas que solicitam o ELK.

Posso definir as opções de ajuste do ELK para o site inteiro em vez de no front matter de cada diagrama?

Sim. elk é uma propriedade de nível superior no schema de configuração do Mermaid, então você pode passá-la para mermaid.initialize() junto com layout, por exemplo, layout: 'elk' com um objeto elk contendo mergeEdges: true e nodePlacementStrategy: 'NETWORK_SIMPLEX'. Uma diretiva %%{init}%% aceita o mesmo objeto elk para um único diagrama. O front matter de um diagrama individual continua sobrescrevendo os valores definidos para o site inteiro.