- oxdraw é uma ferramenta de ‘Diagram as Code’ escrita em Rust, projetada para editar diagramas baseados em código visualmente e mantê-los de forma reproduzível
- Os diagramas são escritos em sintaxe Mermaid e, pela interface web, é possível ajustar por arraste posições de nós, cores, conexões e mais
- As modificações visuais são salvas como comentários dentro do arquivo Mermaid, mantendo compatibilidade com outras ferramentas Mermaid
- É composto por uma CLI e um editor web baseado em React, com suporte tanto a renderização por linha de comando quanto ao modo de edição em tempo real
- Ao combinar a produtividade dos diagramas gerados por código com a liberdade da edição visual, vem ganhando destaque como alternativa a ferramentas GUI como o Lucidchart
Visão geral do projeto
- O objetivo do oxdraw é criar e manter diagramas de alta qualidade com facilidade por meio de uma sintaxe declarativa e reproduzível
- Os diagramas são escritos em sintaxe Mermaid, e os ajustes visuais são feitos na interface web
- O que o usuário altera visualmente é refletido no código-fonte original, permitindo controle de versão e automação
- As alterações são registradas na forma de comentários (comments) dentro do arquivo Mermaid, preservando compatibilidade total com outras ferramentas do ecossistema Mermaid
- O repositório é composto por uma CLI baseada em Rust e uma interface web baseada em React, e a CLI compila arquivos
.mmd em imagens
Visão do projeto
- O desenvolvedor já usava Mermaid no passado para criar diagramas de arquitetura e visualizar codebases, mas, por causa das limitações de edição detalhada, precisava migrar para ferramentas como o Lucidchart
- O oxdraw tem como objetivo combinar a automação baseada em código do Mermaid com a liberdade visual do Lucidchart
- Com isso, busca elevar a qualidade visual sem abrir mão da reprodutibilidade, colaboração e automação dos diagramas gerados por código
Como usar
- Pode ser instalado via Cargo:
cargo install oxdraw
- Renderização de diagrama:
oxdraw --input flow.mmd
- Executar o editor interativo:
oxdraw --input flow.mmd --edit
- A CLI recebe um arquivo Mermaid como entrada e gera saída em SVG ou PNG; com a opção
--edit, inicia um editor web local
Explicação das flags da CLI
-i, --input : arquivo-fonte Mermaid de entrada-o, --output : define o caminho para salvar o resultado renderizado--png: gera saída em formato PNG--scale : ajusta a escala da renderização PNG (padrão: 10.0)--edit: executa o editor visual--serve-host / --serve-port : definem endereço e porta do servidor do editor (padrão: 127.0.0.1:5151)-b, --background-color : define a cor de fundo (somente SVG)-q, --quiet: suprime mensagens como a de conclusão da renderização
Recursos do frontend
- Manipulação de nós e arestas
- Exclusão do nó ou aresta selecionado (com suporte às teclas Delete/Backspace)
- Definição individual e restauração de cor do nó, borda e cor do texto
- Configuração de cor da aresta, estilo de linha (contínua/pontilhada) e direção da seta
- Adição e remoção de pontos de controle (control points) arrastáveis no caminho da aresta
- Interação com o canvas e o editor
- Ao arrastar nós, exibe snap na grade e guias de alinhamento
- Move nós com Shift+setas
- Arraste as handles da aresta para modificar o caminho; clique duplo para adicionar/remover handles
- Suporte a movimentação por subgrafo — move junto os nós e arestas do grupo
- O painel de código-fonte reflete o arquivo Mermaid em tempo real e oferece salvamento automático e indicação de status (salvando/erro etc.)
- A barra de ferramentas superior mostra o caminho atual do arquivo e o status de salvamento
Stack técnica e licença
- Composto por Rust 55.7%, TypeScript 40.0%, CSS 3.4% e outros 0.9%
- Disponibilizado sob a licença MIT, permitindo uso e modificação livres
- Atualmente conta com 506 estrelas e 10 forks, recebendo atenção ativa da comunidade
Avaliação geral
- O oxdraw é uma nova abordagem que combina a automação do gerenciamento de diagramas baseado em código com a intuitividade da edição visual
- Mantém compatibilidade total com o ecossistema Mermaid, aproveitando o desempenho do Rust e a UI interativa do React
- Vem chamando atenção como uma ferramenta que oferece um fluxo de trabalho colaborativo para diagramas tanto para desenvolvedores quanto para designers
1 comentários
Comentários do Hacker News
Projeto realmente muito legal. Acho que a escolha de se basear em Mermaid.js faz sentido, já que ela é provavelmente a biblioteca declarativa de diagramas mais popular no momento
Se quiser dar suporte a tipos de diagrama mais complexos, também vale a pena olhar a D2 Language. Ela oferece uma abordagem declarativa bem mais flexível
Pessoalmente, estou usando com uma porta do MacPorts que eu mesmo criei
Se eu acabar usando com frequência, pretendo contribuir com ela para o repositório oficial do MacPorts
Mas a ausência de tags Git ou releases no GitHub vinculadas às releases do Cargo dificulta o empacotamento
Por enquanto, estou contornando isso assumindo que um commit específico (
9ccd9bf53f9a309ccda42b5c17e9c1056493fb90) corresponde à release 0.1.0A porta em questão pode ser vista aqui
Este projeto é exatamente o tipo de coisa que eu estava procurando. Há um recurso que eu realmente gostaria de ver em uma solução de diagramas declarativos
É uma função de popup que mostre informações adicionais ou diagramas aninhados ao passar o mouse
Por exemplo, você quer poder compartilhar um link para que a pessoa veja diretamente o diagrama com popups e elementos aninhados,
ou bastaria compartilhar só o arquivo
.mmdpara abrir via CLI?A segunda opção seria rápida de implementar, mas a primeira talvez exija algo como self-hosting com ngrok ou uma implantação na nuvem
Outra possibilidade seria adicionar um recurso de exportar para HTML, para que os popups funcionem sem depender da CLI
Parabéns por lançar o projeto. Foi interessante ver como ele usa uma sintaxe declarativa para definir relações e permite um nível de customização detalhada que layouts automáticos existentes normalmente não conseguem oferecer
Mas no
Cargo.tomlele aparece como licenciado em MIT, enquanto no repositório não há arquivo de licençaSeria bom adicionar isso para ficar visível diretamente no GitHub
Projeto muito necessário. Eu uso principalmente PlantUML, mas quando o diagrama passa de 5 componentes, gasto algo como 20% a 30% do tempo ajustando layout
Achei interessante a abordagem de usar comentários para influenciar o mecanismo de layout. Parece útil ter as coordenadas de certos componentes como restrições fixas e deixar o restante ser organizado automaticamente
Se o diagrama também entrar no versionamento junto com as mudanças de código, code review e gestão de arquitetura ficam muito mais naturais
A qualidade de layout do Mermaid é baixa, e é frustrante que o GitHub ignore pedidos de suporte a PlantUML
Parece que a adoção de diagrams as code acaba sendo determinada pelos formatos que as principais plataformas suportam
Em vez de criar um novo padrão, acho mais realista investir em melhorias como renderização baseada em peso dos elementos
Essa discussão também aparece na discussão da comunidade do GitHub
Eu realmente queria que o PlantUML resolvesse esse tipo de problema
Isso parece uma espécie de versão turbinada da linguagem dot do Graphviz
Traz variáveis e uma sintaxe mais limpa, mas os conceitos básicos são parecidos
Veja a documentação do Graphviz
O Mermaid.js tem o conceito de mecanismos de layout
Como o @mermaid-js/layout-elk, por exemplo
Fico curioso se você já pensou em implementar seu algoritmo como um mecanismo de layout automático para o Mermaid
Projeto legal. Vi pelo celular e o botão para adicionar nós não apareceu
Outra função que eu gostaria de ver é recolher nós descendentes (collapse downstream nodes). Talvez saia um pouco do escopo, mas seria bem útil
.mmdmanualmente. Mas acho uma ótima sugestãoA função de recolher nós descendentes também combinaria bem com o recurso de animação que outro usuário pediu