Como usar o oxdraw: editor visual de diagramas Mermaid com CLI e suporte a Rust

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:

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

1. Crie um diagrama de arquitetura do sistema em Mermaid
2. Abra-o no oxdraw e organize visualmente os blocos
3. Salve o arquivo e adicione-o ao Git
4. 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.