- Na versão 0.7.1 do D2, foi adicionada a função de renderizar diagramas de texto em ASCII
- É possível usar diagramas ASCII simples em comentários de código para explicar o fluxo de funções ou classes
- Por padrão, usa caracteres Unicode, mas é possível escolher ASCII padrão com uma flag de opção
- Esse recurso está em fase alfa e ainda não oferece suporte a alguns estilos, caracteres especiais e determinadas formas
- É possível experimentar a renderização ASCII diretamente no D2 Playground e na extensão para Vim
Introdução à renderização ASCII do D2
A partir da versão mais recente do D2 (0.7.1), foi adicionada a função de saída ASCII para diagramas de texto.
Arquivos de saída com extensão .txt são renderizados automaticamente com o renderizador ASCII.
É possível ver exemplos na extensão D2 para Vim; ao abrir um arquivo .d2 e salvar pelo painel de preview, dá para acompanhar em tempo real a saída do diagrama ASCII.
Uso na documentação de código
Os diagramas ASCII são mais práticos quando inseridos em comentários de código-fonte
- Ao adicionar um diagrama simples ao lado de uma função ou classe pequena, ele ajuda a entender o código de forma mais intuitiva do que uma explicação do fluxo
- Na extensão para Vim, é possível escrever código D2 e converter a seleção imediatamente em um diagrama ASCII
Escolha entre Unicode e ASCII padrão
A renderização ASCII padrão usa caracteres Unicode de desenho de caixas, oferecendo uma saída visualmente melhor
- Se você quiser máxima portabilidade, pode usar a flag de opção
--ascii-mode=standardpara renderizar também com caracteres ASCII comuns
Limitações atuais
Esse recurso de renderização ASCII está em fase alfa
- Pode haver muitos casos de borda, pontos de melhoria e bugs
- O envio de relatórios de bugs ou feedback no site é incentivado
Principais limitações
- Sem suporte a estilos
- Animações, fontes etc. não fazem sentido em ASCII
- Há planos de avaliar futuramente algum suporte limitado a estilos, como cores de terminal
- Temas também não são suportados
double-border,multipleetc. estão na lista de melhorias futuras
- Espaçamento irregular
- No processo de conversão para ASCII, o posicionamento das caixas pode ficar mais irregular em comparação com SVG
- Itens que não podem ser renderizados
- Ainda não há suporte para textos especiais como Markdown, Latex e código
- Imagens e ícones, classes UML, tabelas SQL etc. não podem ser renderizados
- Ainda será decidido futuramente se esses itens serão removidos ou exibidos como placeholders
- Algumas formas não são suportadas
- Formas curvas como nuvens e círculos não são bem representadas em ASCII
- Essas formas são substituídas por retângulos, com um pequeno ícone no canto superior esquerdo para distinguir o tipo
Experimente você mesmo
Esse recurso pode ser usado imediatamente no D2 Playground
- Você pode abrir o bloco de código fornecido e testar a renderização ASCII diretamente
1 comentários
Comentários no Hacker News
Olá, pessoal dev. Queria compartilhar um recurso novo que adicionei hoje de manhã. Ainda está em fase alfa e já apareceu uma issue no GitHub. Se quiser pular o post do blog e ir direto ver, dá para conferir aqui . Há um exemplo maior também neste link
.txt? Já uso ELK para a maioria dos meus diagramas em D2Queria entender qual é o valor disso em comparação com o Mermaid. Gosto do design e de como funciona, mas queria saber se existe um motivo prático para migrar do Mermaid. Também acho que essas ferramentas em geral pecam por não oferecerem, nos resultados gerados automaticamente, a capacidade de ajustar manualmente posição e tamanho das caixas com valores x/y
Apesar de a sintaxe do D2 ser muito atraente, eu vinha usando mais o Mermaid por causa do tooling. Mas esse recurso é algo realmente novo em grande escala, e eu nunca vi isso no Mermaid. Também cria uma boa ponte com o asciiflow.com
Gostei do recurso de converter a partir de ASCII. Mas, quando for preciso atualizar o diagrama, como recuperar o código-fonte original em D2?
Sempre gostei mais do D2 do que do Mermaid, mas, na minha opinião, o layout em grade fica praticamente inútil por causa da seguinte issue (issue relacionada). Se for preciso ajustar unidades em pixel manualmente, é como perder o propósito desse tipo de ferramenta
Já mantive e compartilhei várias vezes uma lista de ferramentas de texto para diagrama baseadas em navegador. Uma coisa que descobri recentemente é que a versão online do D2 não roda de forma puramente no navegador; um servidor de backend gera os diagramas. Queria saber se o D2 consegue funcionar sozinho apenas no cliente (navegador) e se a extensão mencionada neste post também funciona offline
d2.js, um wrapper em torno do port wasm do D2. Ainda não foi lançado oficialmente, mas em breve vamos anunciar isso separadamenteGostaria que houvesse um repositório oficial em Python. Quero usar em notebook, mas no momento sou praticamente obrigado a usar Databricks, o que é incômodo
Ficou muito legal visualmente. Também vi o post anterior sobre suporte a C4! Vou dar uma olhada, porque em breve vou precisar fazer modelagem C4
Recurso realmente muito legal. Nunca tinha ouvido falar do D2, mas gostei muito do fato de dar para criar gráficos direto no terminal e ainda renderizar tudo de forma bonita. Pretendo testar logo
.svgao vivo por meio de um servidor HTTP em tempo real. Se você deixar o navegador e o vim lado a lado, também consegue ver as atualizações em tempo real. Descobri o D2 há um ano e, desde então, uso em todos os meus diagramasA extensão para vim é realmente incrível