Use subgrafos de fluxograma aninhados para contêineres com título, inclusive os blocos folha. Quando contêineres vazios forem renderizados de forma inadequada, adicione um espaçador invisível dentro de cada folha. Isso preserva a hierarquia visível; confira o resultado no renderizador do Obsidian instalado.

Este guia cria um diagrama neutro: um bloco externo chamado Collection, contendo Group A e Group B, com contêineres folha com título dentro de cada grupo. O objetivo é manter essas folhas com aparência de contêineres com cabeçalhos, em vez de substituí-las por retângulos comuns com rótulos.

O que deve representar um bloco folha com título?

Represente cada contêiner visível com um subgraph, tenha ele ou não outro bloco significativo dentro. A documentação do Mermaid apresenta subgrafos, IDs explícitos de subgrafos e aninhamento nos exemplos de fluxogramas. Uma declaração comum de nó, como leafA["Block A"], cria um nó com rótulo; ela não declara um contêiner com título. Consulte Fluxogramas — sintaxe básica do Mermaid.

Neste exemplo, diferencie o modelo visível dos elementos que dão suporte ao layout. Collection, os grupos e os blocos folha são os elementos significativos. Um espaçador é um detalhe de implementação usado para dar conteúdo a um contêiner folha para fins de layout. Adicionar esse auxiliar não transforma a declaração da folha de subgrafo em nó.

Essa distinção também define o limite desta abordagem: ela produz um diagrama cujas folhas visíveis continuam sendo contêineres com título, mas o código-fonte inclui nós auxiliares comuns. Se o requisito proíbe toda declaração de nó, inclusive auxiliares invisíveis, esta solução alternativa não atende a essa exigência mais estrita.

Confira qual renderizador sua instalação do Mac usa

No Obsidian, abra Settings na barra lateral, selecione General e anote a versão do aplicativo. A documentação de configurações do Obsidian indica que General é onde ficam as informações da versão. Use essa versão para escolher as notas de versão relevantes.

Há uma diferença importante entre renderizadores. As notas oficiais de versão de 22 de outubro de 2026 identificam o Desktop 1.15.0 como acesso antecipado e informam que ele renderiza a sintaxe Mermaid por meio da biblioteca Pele do Obsidian, com compatibilidade com a sintaxe Mermaid 12.1.0. A mesma versão altera as classes geradas para usar as classes de Pele. Não presuma que uma instalação mais antiga use Pele, nem que compatibilidade signifique uma saída idêntica à do Mermaid.js. Consulte Obsidian 1.15.0 Desktop (acesso antecipado).

A documentação do Mermaid consultada para este guia exibe a versão 12.2.0. Essa versão é diferente do nível de compatibilidade mencionado nas notas de versão do Obsidian. Considere a documentação, um editor online e o aplicativo instalado como ambientes separados até verificar o mesmo exemplo em cada um.

Na primeira tentativa, mantenha o diagrama sem configurações específicas de renderizador e seletores de folha de estilo externos. O exemplo abaixo usa subgrafos e estilos locais ao diagrama, oferecendo um ponto de partida simples para conferir sua instalação.

Crie os contêineres aninhados em uma nota do Obsidian

Abra uma nota no modo de edição e cole o bloco completo abaixo, incluindo as cercas de abertura e fechamento. O Obsidian documenta diagramas Mermaid como blocos de código cercados com o identificador de linguagem mermaid. Esse formato documentado para notas não exige um plugin adicional de diagramas. Consulte Sintaxe de formatação avançada.

```mermaid
flowchart TB
    subgraph collection["Collection"]
        subgraph groupA["Group A"]
            subgraph blockA["Block A"]
                spacerA[" "]
            end
            subgraph blockB["Block B"]
                spacerB[" "]
            end
        end
        subgraph groupB["Group B"]
            subgraph blockC["Block C"]
                spacerC[" "]
            end
        end
    end

    classDef spacer fill:transparent,stroke:transparent,color:transparent;
    class spacerA,spacerB,spacerC spacer;
```

Pressione Cmd+E para alternar entre a edição e a Reading view. Use a visualização de leitura para inspecionar o diagrama final sem que o cursor de edição revele o código-fonte. Esses controles estão documentados em Visualizações e modo de edição do Obsidian.

O resultado esperado tem seis contêineres visíveis com título: uma coleção, dois grupos e três blocos folha. Cada folha contém um auxiliar cujo rótulo é um único espaço. A classe spacer solicita preenchimento, borda e texto transparentes. Isso combina o mecanismo de classes documentado pelo Mermaid com uma solução alternativa de layout; o Mermaid documenta classDef e a atribuição de classes na referência de estilo de fluxogramas.

O exemplo foi conferido em relação à sintaxe documentada; ele não foi renderizado em uma sessão do Obsidian para Mac durante a elaboração deste artigo. Portanto, a verificação de aceitação é visual e local: os seis títulos devem aparecer, cada grupo deve conter as folhas correspondentes e nenhum retângulo espaçador deve estar visível. O espaçamento exato e as posições dos elementos irmãos não são critérios de aceitação.

Altere os rótulos sem mudar a hierarquia

Comece alterando apenas os títulos entre aspas. Mantenha collection, groupA, blockA e os outros IDs distintos. Assim, fica mais fácil comparar a versão editada com o exemplo inicial.

Para adicionar outra folha, copie um subgrafo folha completo, atribua IDs novos tanto ao subgrafo quanto ao espaçador e adicione o novo ID do espaçador à atribuição final de classe. Coloque-o antes de end do grupo que o contém. Por exemplo, uma quarta folha em Group B deve ficar ao lado de blockC, dentro de groupB.

Leia as instruções de fechamento de dentro para fora: feche a folha, feche o grupo e, em seguida, feche a coleção. A indentação deixa essa estrutura visível durante a edição, mas é a posição de cada end que o código-fonte precisa expressar corretamente.

Por que usar espaçadores em vez de subgrafos vazios?

O comportamento de contêineres vazios variou entre renderizadores e versões. A issue 5402 do Mermaid relata que um subgrafo vazio falha com ELK no Mermaid 10.8.0, enquanto o exemplo fornecido com Dagre funciona. Trata-se de um relato histórico sobre uma configuração específica, não de evidência de que todo renderizador atual rejeite subgrafos vazios. Consulte Elk renderer not wokring on empty subgraph.

A conclusão prática é evitar que o comportamento de contêineres vazios seja a única base de um diagrama destinado a uma instalação desconhecida. A abordagem com espaçadores dá conteúdo explícito a cada folha e mantém o título significativo no subgrafo.

Use este guia de decisão para escolher o grau de rigor necessário para o código-fonte:

Requisito Abordagem inicial O que verificar
As folhas visíveis devem continuar sendo contêineres com título Subgrafos aninhados com espaçadores transparentes Títulos, contenção e auxiliares ocultos
O código-fonte não pode conter nós auxiliares Experimente subgrafos folha vazios no renderizador de destino Se todas as folhas vazias são renderizadas corretamente
Os blocos folha receberão itens reais mais tarde Mantenha os subgrafos folha e substitua os espaçadores Remova apenas os auxiliares que não forem mais necessários
Os blocos precisam de posicionamento deliberado em colunas Avalie os diagramas de blocos do Mermaid separadamente Suporte à sintaxe instalada e apresentação dos títulos

A documentação dedicada a diagramas de blocos do Mermaid descreve blocos compostos, colunas e espaçamento explícito. Vale avaliar esses recursos quando o posicionamento for a principal tarefa. Eles não garantem, por si só, que uma conversão preserve exatamente esta apresentação de contêineres com título. Consulte Documentação de diagramas de blocos.

Diagnostique um resultado que parece errado

Altere uma coisa por vez. Mantenha uma cópia do exemplo inicial completo em uma nota separada para distinguir uma diferença de renderizador de um erro de edição.

  1. A nota mostra código em vez de um diagrama. Confira se a cerca de abertura usa mermaid e depois alterne para Reading view. Compare a cerca com o formato de diagrama documentado pelo Obsidian.
  2. Uma folha parece um retângulo comum com rótulo. Inspecione sua declaração. Ela deve começar com subgraph, com o espaçador em uma linha separada dentro dela.
  3. Um pequeno retângulo continua visível dentro de uma folha. Compare o ID do espaçador com a instrução final class. Remova temporariamente o estilo para identificar qual auxiliar está visível e depois restaure-o.
  4. Um bloco aparece no grupo errado. Confira a sequência de instruções end de fechamento antes de ajustar as configurações de layout.
  5. O diagrama funciona online, mas fica diferente no Obsidian. Compare as notas de versão do aplicativo instalado com a versão do renderizador online. Use o exemplo local que funciona como referência.

Preserve a contenção antes de ajustar o posicionamento

Depois que os títulos e a contenção estiverem corretos, decida se a organização é suficientemente legível. Não substitua um subgrafo folha por um nó apenas para diminuir seu retângulo: essa alteração muda a representação que você queria preservar.

Da mesma forma, adicione conectores apenas quando o diagrama precisar representar uma relação além da contenção. O Mermaid documenta uma limitação de direção: conectar um nó dentro de um subgrafo a um elemento externo faz com que esse subgrafo herde a direção do pai. Confira o layout novamente depois de adicionar essas arestas. Consulte Direção em subgrafos.

Por fim, inspecione a nota na largura em que costuma lê-la. Mantenha a versão que mostra com clareza a coleção, seus grupos e as folhas com título. O resultado útil é uma hierarquia de contenção legível cujos blocos folha continuam sendo subgrafos, com eventuais auxiliares invisíveis de layout devidamente identificados e fáceis de remover depois.

Fontes