oxdraw - é uma ferramenta para criar e editar diagramas usando uma sintaxe declarativa e com a possibilidade de edição visual através de uma interface web. Ela é baseada em Mermaid, mas permite não apenas escrever o código dos diagramas, como também ajustar a aparência (posições, cores, linhas, estilos) diretamente na interface, enquanto todas as alterações são automaticamente salvas de volta no arquivo .mmd original como comentários.
Graças a isso, os diagramas permanecem determinísticos, versionáveis e compatíveis com outras ferramentas Mermaid.
Links
- Repositório: https://github.com/RohanAdwankar/oxdraw
- Documentação do Mermaid: https://mermaid.js.org
Recursos do oxdraw
- Criação e edição de diagramas na sintaxe Mermaid
- Editor visual com suporte a posicionamento, conexões e esquemas de cores
- Salvamento automático das alterações no arquivo .mmd original como comentários
- CLI em Rust para compilar arquivos .mmd → imagens (PNG, SVG, etc.)
- Interface web em React para edição interativa
Instalação
1. Clonar o repositório
2. Instalar dependências
Rust (para o CLI)
Certifique-se de que o Rust está instalado. Caso não esteja:
Compile o CLI:
Node.js (para a interface web)
Instale as dependências do frontend:
Uso
1. Criar um diagrama
Crie um arquivo Mermaid:
2. Executar a interface web
Abra no navegador: http://localhost:5173
Carregue o arquivo example.mmd e comece a editar — você pode mover nós, alterar cores, estilos e conexões.
Todas as alterações são automaticamente salvas como comentários no arquivo, por exemplo:
A-->B
B-->C
%% position: A(100,200), B(200,300)
Compilação de diagramas
Após a edição, é possível gerar imagens:
São suportados os formatos: SVG, PNG e PDF.
Vantagens do oxdraw
- Total compatibilidade com o Mermaid
- Reprodutibilidade e controle de versão
- Possibilidade de ajuste visual preciso
- Integração rápida com CI/CD para geração automática de diagramas em documentação
Exemplo de cenário de uso
- Crie um diagrama de arquitetura do sistema em Mermaid
- Abra-o no oxdraw e organize visualmente os blocos
- Salve o arquivo e adicione-o ao Git
- Use o CLI para gerar as imagens finais para documentação
Conclusão
oxdraw é uma ferramenta que combina a conveniência da edição visual com a flexibilidade da abordagem declarativa. É especialmente útil para engenheiros, profissionais de DevOps e redatores técnicos que desejam documentar infraestrutura, arquitetura de sistemas ou pipelines de CI/CD em diagramas visuais e reproduzíveis. Com o oxdraw, você pode usar simultaneamente o poder do Mermaid e a simplicidade da interface drag-and-drop, sem perder o controle sobre o código nem a compatibilidade com outras ferramentas. Se você valoriza determinismo, transparência e controle de versão, o oxdraw será uma excelente adição ao seu conjunto de ferramentas.
FAQ
- O que torna o oxdraw melhor que o Mermaid comum?
O Mermaid comum exige posicionamento manual de elementos via código. O oxdraw resolve esse problema, permitindo editar o diagrama visualmente e salvar automaticamente as alterações de posição de volta no arquivo original como comentários — sem perder compatibilidade. - É possível usar o oxdraw sem a interface web?
Sim. A ferramenta CLI escrita em Rust permite compilar arquivos .mmd em imagens sem precisar executar a interface. Isso é útil para automação ou CI/CD. - Onde as alterações são salvas após a edição visual?
Todas as alterações são inseridas no arquivo .mmd original como comentários (por exemplo %% position: ...). Assim, você pode versionar e acompanhar as diferenças no Git. - Quais formatos de exportação são suportados?
Com o CLI é possível exportar diagramas em SVG, PNG ou PDF, tornando o oxdraw ideal para documentação técnica e apresentações. - É possível integrar o oxdraw em projetos existentes?
Sim. O oxdraw é totalmente compatível com o Mermaid, então você pode usá-lo em projetos atuais sem alterar o formato dos diagramas.