- oxdraw es una herramienta de ‘Diagram as Code’ escrita en Rust, diseñada para editar diagramas basados en código de forma visual y mantenerlos en un formato reproducible
- Los diagramas se escriben con sintaxis Mermaid y, mediante una interfaz web, es posible ajustar arrastrando la posición de nodos, colores, conexiones y más
- Los cambios visuales se guardan como comentarios dentro del archivo Mermaid, manteniendo la compatibilidad con otras herramientas de Mermaid
- Está compuesto por un CLI y un editor web basado en React, y admite tanto renderizado por línea de comandos como modo de edición en tiempo real
- Al combinar la productividad de los diagramas generados por código con la libertad de la edición visual, está llamando la atención como una alternativa a herramientas GUI como Lucidchart
Descripción general del proyecto
- El objetivo de oxdraw es crear y mantener fácilmente diagramas de alta calidad mediante una sintaxis declarativa y reproducible
- Los diagramas se escriben con sintaxis Mermaid y los ajustes visuales se realizan en la interfaz web
- Los cambios hechos visualmente por el usuario se reflejan en el código fuente, lo que permite control de versiones y automatización
- Las modificaciones se registran como comentarios (comment) dentro del archivo Mermaid, conservando compatibilidad total con otras herramientas del ecosistema Mermaid
- El repositorio está compuesto por un CLI basado en Rust y una interfaz web basada en React; el CLI compila archivos
.mmd en imágenes
Visión del proyecto
- El desarrollador había usado Mermaid en el pasado para crear diagramas de arquitectura o visualizar bases de código, pero por las limitaciones de edición fina terminaba migrando a herramientas como Lucidchart
- oxdraw busca combinar la automatización basada en código de Mermaid con la libertad visual de Lucidchart
- Con ello, apunta a mantener la reproducibilidad, colaboración y posibilidades de automatización de los diagramas generados por código, al mismo tiempo que mejora su calidad visual
Cómo usarlo
- Se puede instalar con Cargo:
cargo install oxdraw
- Renderizar un diagrama:
oxdraw --input flow.mmd
- Ejecutar el editor interactivo:
oxdraw --input flow.mmd --edit
- El CLI toma archivos Mermaid como entrada y genera salida SVG o PNG; con la opción
--edit ejecuta un editor web local
Explicación de las banderas del CLI
-i, --input : archivo fuente Mermaid de entrada-o, --output : ruta donde guardar el resultado del renderizado--png: salida en formato PNG--scale : ajusta la escala de renderizado PNG (valor predeterminado 10.0)--edit: ejecuta el editor visual--serve-host / --serve-port : define la dirección y el puerto del servidor del editor (predeterminado 127.0.0.1:5151)-b, --background-color : define el color de fondo (solo para SVG)-q, --quiet: suprime mensajes como el de renderizado completado
Funciones del frontend
- Manipulación de nodos y aristas
- Eliminar nodos o aristas seleccionados (compatible con teclas Delete/Backspace)
- Definir y restablecer individualmente color del nodo, borde y color del texto
- Configurar color de la arista, estilo de línea (continua/punteada) y dirección de la flecha
- Agregar y quitar puntos de control (control point) arrastrables en la ruta de la arista
- Interacción con el lienzo y el editor
- Al arrastrar nodos, muestra ajuste a cuadrícula y guías de alineación
- Mover nodos con Shift+flechas
- Modificar rutas arrastrando los handles de las aristas; doble clic para agregar/eliminar handles
- Soporta movimiento por subgrafo: mueve juntos los nodos y aristas dentro del grupo
- El panel de fuente refleja el archivo Mermaid en tiempo real y ofrece guardado automático e indicadores de estado (guardando/error, etc.)
- La barra de herramientas superior muestra la ruta actual del archivo y el estado de guardado
Composición técnica y licencia
- Está compuesto por Rust 55.7%, TypeScript 40.0%, CSS 3.4% y otros 0.9%
- Se publica bajo licencia MIT, lo que permite su uso y modificación libremente
- Actualmente cuenta con 506 estrellas y 10 forks, mostrando un activo interés de la comunidad
Evaluación general
- oxdraw propone un nuevo enfoque que combina la automatización de la gestión de diagramas basada en código con la intuitividad de la edición visual
- Mantiene compatibilidad total con el ecosistema Mermaid, mientras aprovecha el rendimiento de Rust y la UI interactiva de React
- Está destacando como una herramienta que ofrece un flujo de trabajo de diagramas colaborativo tanto para desarrolladores como para diseñadores
1 comentarios
Opiniones de Hacker News
Es un proyecto realmente genial. Creo que basarse en Mermaid.js fue una buena elección, ya que probablemente sea la biblioteca de diagramas declarativos más popular en este momento.
Si quieren soportar tipos de diagramas más complejos, también valdría la pena revisar D2 Language. Ofrece un enfoque declarativo mucho más flexible.
En lo personal, hice un port para MacPorts y lo estoy usando.
Si termino usándolo con frecuencia, pienso contribuirlo al repositorio oficial de MacPorts.
Pero es incómodo empaquetarlo porque no hay tags de Git ni releases en GitHub vinculados a los lanzamientos de Cargo.
Por ahora lo resolví temporalmente asumiendo que cierto commit (
9ccd9bf53f9a309ccda42b5c17e9c1056493fb90) corresponde al release 0.1.0.El port relacionado se puede ver aquí.
Este proyecto es exactamente lo que estaba buscando. Hay una función que realmente me gustaría ver en una solución de diagramas declarativos.
Es una función de popup que muestre información adicional o diagramas anidados al pasar el mouse.
Por ejemplo, si lo que quieres es compartir un enlace para que se pueda ver de inmediato un diagrama con popups y anidación,
o si te bastaría con compartir solo el archivo
.mmdpara abrirlo con el CLI.Lo segundo se puede implementar rápido, pero lo primero podría requerir self-hosting tipo ngrok o un despliegue en la nube.
Otra opción sería agregar una función para exportar a HTML y que los popups funcionen incluso sin CLI.
Felicidades por publicar el proyecto. Me impresionó cómo define relaciones con una sintaxis declarativa y permite una personalización detallada que los layouts automáticos existentes no logran.
Pero en
Cargo.tomlaparece como licencia MIT, aunque en el repositorio no hay archivo de licencia.Estaría bien agregarlo para que se pueda verificar directamente en GitHub.
Es un proyecto muy necesario. Yo uso sobre todo PlantUML, pero cuando los componentes pasan de 5, termino gastando entre 20% y 30% del tiempo ajustando el layout.
Me parece interesante el enfoque de usar anotaciones para influir en el motor de layout. Podría ser útil fijar las coordenadas de ciertos componentes como restricciones fijas y dejar que el resto se distribuya automáticamente.
Si los diagramas también entran en control de versiones junto con los cambios de código, entonces la revisión de código y la gestión de arquitectura se vuelven mucho más naturales.
La calidad del layout de Mermaid es baja, y es una pena que GitHub ignore las solicitudes para dar soporte a PlantUML.
Parece que la adopción de ‘diagrams as code’ la determina el formato que soportan las plataformas principales.
Más que crear un nuevo estándar, creo que sería más realista mejorar cosas como el renderizado basado en pesos de elementos.
Esto también se discute en la discusión de la comunidad de GitHub.
Ojalá PlantUML pudiera resolver este tipo de problema.
Esto se parece a una versión mejorada del lenguaje dot de Graphviz.
Ofrece variables y una sintaxis más limpia, pero el concepto base es similar.
Consulta la documentación de Graphviz.
Mermaid.js tiene el concepto de motores de layout.
Como @mermaid-js/layout-elk.
Me pregunto si has pensado implementar tu algoritmo como un motor de layout automático para Mermaid.
Muy buen proyecto. Lo vi desde el móvil y no se ve el botón para agregar nodos.
Otra función que me gustaría es colapsar nodos descendentes (collapse downstream nodes). Quizá se salga del alcance, pero sería bueno tenerla.
.mmd. Pero me parece una buena sugerencia.La función de colapsar nodos descendentes también podría combinar bien con la función de animación que pidió otro usuario.