- oxdraw, Rust ile yazılmış bir 'Diagram as Code' aracıdır; kod tabanlı diyagramları görsel olarak düzenlemek ve yeniden üretilebilir biçimde korumak için tasarlanmıştır
- Diyagramlar Mermaid sözdizimi ile yazılır ve web arayüzü üzerinden düğüm konumları, renkler, bağlantı çizgileri gibi öğeler sürükleyerek ayarlanabilir
- Görsel düzenleme değişiklikleri, Mermaid dosyası içinde yorum biçiminde saklanır; böylece diğer Mermaid araçlarıyla uyumluluk korunur
- Araç, bir CLI ve React tabanlı web editöründen oluşur; komut satırı render alma ve gerçek zamanlı düzenleme modunun ikisini de destekler
- Kodla üretilen diyagramların üretkenliği ile görsel düzenlemenin esnekliğini birleştirerek, Lucidchart gibi GUI araçlarına bir alternatif olarak öne çıkar
Proje özeti
- oxdraw'ın hedefi, bildirimsel ve yeniden üretilebilir bir sözdizimi aracılığıyla yüksek kaliteli diyagramları kolayca oluşturmak ve sürdürmektir
- Diyagramlar Mermaid sözdizimiyle yazılır, görsel ayarlamalar ise web arayüzünde yapılır
- Kullanıcının görsel olarak yaptığı değişiklikler özgün koda yansıtılır; böylece sürüm kontrolü ve otomasyon mümkün olur
- Değişiklikler Mermaid dosyası içinde yorum (comment) biçiminde kaydedilir; bu sayede Mermaid ekosistemindeki diğer araçlarla tam uyumluluk korunur
- Depo, Rust tabanlı bir CLI ve React tabanlı bir web arayüzünden oluşur; CLI,
.mmd dosyalarını görsellere derler
Proje vizyonu
- Geliştirici geçmişte Mermaid kullanarak mimari diyagramlar veya kod tabanı görselleştirmeleri oluşturdu, ancak ince ayar düzenleme sınırları nedeniyle Lucidchart gibi araçlara geçmek zorunda kaldı
- oxdraw, Mermaid'in kod tabanlı otomasyonu ile Lucidchart'ın görsel esnekliğini birleştirmeyi hedefliyor
- Böylece kodla üretilen diyagramların yeniden üretilebilirlik, iş birliğine uygunluk ve otomasyon olanağını korurken, görsel kaliteyi artırmayı amaçlıyor
Kullanım
- Cargo ile kurulabilir:
cargo install oxdraw
- Diyagram render alma:
oxdraw --input flow.mmd
- Etkileşimli editörü çalıştırma:
oxdraw --input flow.mmd --edit
- CLI, Mermaid dosyasını girdi olarak alıp SVG veya PNG çıktısı üretir;
--edit seçeneği ile yerel web editörü başlatılır
CLI bayrakları açıklaması
-i, --input : Mermaid kaynak dosyası girdisi-o, --output : Render çıktısının kaydedileceği yol--png: PNG biçiminde çıktı--scale : PNG render ölçeğini ayarlama (varsayılan 10.0)--edit: Görsel editörü çalıştırma--serve-host / --serve-port : Editör sunucusunun adresi ve portu (varsayılan 127.0.0.1:5151)-b, --background-color : Arka plan rengini belirtme (yalnızca SVG)-q, --quiet: Render tamamlandı mesajı gibi çıktıları bastırma
Frontend özellikleri
- Düğüm ve kenar işlemleri
- Seçili düğüm veya kenarı silme (Delete/Backspace tuşları desteklenir)
- Düğüm rengi, kenarlık ve metin rengini ayrı ayrı belirleme ve sıfırlama
- Kenar rengi, çizgi stili (düz/kesik) ve ok yönünü ayarlama
- Kenar yoluna sürüklenebilir kontrol noktaları (control point) ekleme ve kaldırma
- Tuval ve editör etkileşimi
- Düğüm sürüklerken ızgaraya yapışma ve hizalama kılavuzları gösterilir
- Shift+ok tuşları ile düğüm taşıma
- Kenar tutamaçlarını sürükleyerek yolu değiştirme, çift tıklayarak tutamaç ekleme/silme
- Alt grafik düzeyinde taşıma desteği — grup içindeki düğümler ve kenarlar birlikte taşınır
- Kaynak paneli, Mermaid dosyasını gerçek zamanlı yansıtır; otomatik kaydetme ve durum göstergesi (kaydediliyor/hata vb.) sunar
- Üst araç çubuğunda mevcut dosya yolu ve kayıt durumu gösterilir
Teknik yapı ve lisans
- Yapı şu oranlardan oluşur: Rust %55.7, TypeScript %40.0, CSS %3.4, diğer %0.9
- MIT lisansı ile yayımlanmıştır; serbest kullanım ve değiştirme mümkündür
- Şu anda 506 Star ve 10 Fork sayısına sahiptir; topluluktan aktif ilgi görmektedir
Genel değerlendirme
- oxdraw, kod tabanlı diyagram yönetiminin otomasyonu ile görsel düzenlemenin sezgiselliğini birleştiren yeni bir yaklaşım sunuyor
- Mermaid ekosistemiyle tam uyumluluğu korurken, Rust'ın performansından ve React'in etkileşimli kullanıcı arayüzünden yararlanıyor
- Hem geliştiriciler hem de tasarımcılar için iş birliğine açık bir diyagram iş akışı sunan bir araç olarak dikkat çekiyor
1 yorum
Hacker News yorumu
Gerçekten harika bir proje. Mermaid.js tabanlı seçim bence şu anda en popüler deklaratif diyagram kütüphanesi olduğu için çok yerinde
Daha karmaşık diyagram türlerini desteklemek için D2 Language'e de bakılabilir. Çok daha esnek bir deklaratif yaklaşım sunuyor
Ben şahsen bir MacPorts portu hazırlayıp kullanıyorum
Sık kullanmaya başlarsam resmi MacPorts deposuna katkı yapmayı düşünüyorum
Ancak Cargo sürümleriyle bağlantılı Git etiketi ya da GitHub release olmadığı için paketleme zahmetli
Şimdilik belirli bir commit'i (
9ccd9bf53f9a309ccda42b5c17e9c1056493fb90) 0.1.0 sürümü kabul ederek geçici bir çözüm uyguluyorumİlgili portu burada görebilirsiniz
Bu proje tam olarak aradığım şey. Deklaratif diyagram çözümlerinde özellikle görmek istediğim bir özellik var
O da fareyle üzerine gelindiğinde ek bilgi ya da iç içe diyagramlar gösteren bir açılır pencere özelliği
Örneğin bir bağlantı paylaşıldığında, açılır pencereler ve iç içe yapılar içeren diyagramın doğrudan görüntülenmesini mi istiyorsunuz,
yoksa sadece
.mmddosyasını paylaşıp CLI ile açmanın yeterli olması mı bekleniyor?İkincisi hızlıca uygulanabilir, ama birincisi ngrok benzeri self-hosting ya da bulut dağıtımı gerektirebilir
Ya da HTML dosyası olarak dışa aktarma (export) özelliği eklenip, CLI olmadan da açılır pencerelerin çalışması sağlanabilir
Projeyi duyurduğunuz için tebrikler. İlişkileri deklaratif sözdizimiyle tanımlayıp, mevcut otomatik yerleşim sistemlerinin yapamadığı ince ayarlı özelleştirmeleri mümkün kılması etkileyici
Ancak
Cargo.tomliçinde MIT lisansı belirtilmiş olsa da depoda lisans dosyası yokGitHub üzerinde doğrudan görülebilmesi için eklenirse iyi olur
Gerçekten ihtiyaç duyulan bir proje. Ben çoğunlukla PlantUML kullanıyorum ama bileşen sayısı 5'i geçince yerleşimi düzeltmeye zamanımın %20-30'unu harcıyorum
Yorumları kullanarak yerleşim motoruna etki etme yaklaşımı ilginç. Belirli bileşenlerin koordinatlarını sabit kısıtlar olarak bırakıp geri kalanını otomatik yerleştirmek kullanışlı olabilir
Kod değişiklikleriyle birlikte diyagramların da sürüm kontrolüne dahil edilmesi, kod incelemesi ve mimari yönetimini çok daha doğal hale getirir
Mermaid'in yerleşim kalitesi düşük ve GitHub'ın PlantUML desteği taleplerini görmezden gelmesi üzücü
Ana platformların desteklediği formatlara göre code as diagrams benimsenmesi şekilleniyor gibi görünüyor
Yeni bir standart oluşturmaktan ziyade, öğe ağırlığı tabanlı render gibi iyileştirmeler daha gerçekçi geliyor
İlgili tartışma GitHub topluluk tartışmasında da ele alınıyor
PlantUML'ün bu tür sorunları çözmesini gerçekten isterdim
Bu, sanki Graphviz'in dot dilinin güçlendirilmiş bir sürümü gibi
Değişkenler ve daha temiz bir sözdizimi sunuyor ama temel kavramlar benzer
Graphviz belgelerine bakabilirsiniz
Mermaid.js içinde bir yerleşim motoru kavramı zaten var
@mermaid-js/layout-elk gibi
Acaba algoritmanızı Mermaid için otomatik yerleşim motoru olarak uygulamayı düşündünüz mü?
Harika proje. Mobilde baktım ama düğüm ekleme düğmesi görünmüyor
Bir diğer görmek istediğim özellik de alt düğümleri daraltma (collapse downstream nodes)
Kapsam dışı olabilir ama olursa güzel olur
.mmdmetnini doğrudan düzenlemek gerekiyor. Ama bence iyi bir öneriAlt düğümleri daraltma özelliği, başka bir kullanıcının talep ettiği animasyon özelliğiyle de iyi örtüşebilir