Mermaid ASCII: Terminalde Mermaid diyagramlarını render etme

 (github.com/lukilabs)
16 puan yazan GN⁺ 2026-01-30 | 1 yorum | WhatsApp'ta paylaş
  • beautiful-mermaid, Mermaid diyagramlarını SVG veya ASCII sanatı olarak render eden ultra hızlı, TypeScript tabanlı bir araçtır
  • 5 diyagram türünü (Flowchart, State, Sequence, Class, ER) destekler ve hem terminalde hem tarayıcıda çalışır
  • 15 yerleşik tema ve Shiki uyumluluğu sayesinde VS Code temaları doğrudan uygulanabilir
  • Mono modu, yalnızca iki renkle tutarlı bir görsel ifade sunar; CSS özel özellikleri ile gerçek zamanlı tema değişimini destekler
  • Yapay zeka destekli programlama ortamlarında veri akışını ve sistem yapısını görselleştirebilen, hafif ve bağımlılıksız bir araç olarak öne çıkar

Genel bakış

  • beautiful-mermaid, Mermaid diyagramlarını SVG veya ASCII/Unicode metin olarak render eden bir araçtır
    • DOM bağımlılığı olmadan çalışır ve çok hızlı render desteği sunar (500 ms içinde 100'den fazla diyagram)
    • Craft ekibi tarafından Craft Agents için geliştirildi
  • Mermaid-ascii (Go tabanlı proje), TypeScript'e port edildi ve özellikleri genişletildi
    • Sequence, Class ve ER diyagram desteği eklendi
    • Unicode kutu karakterleri, aralık ve padding ayarları dahil edildi

Başlıca özellikler

  • Desteklenen diyagram türleri: Flowchart, State, Sequence, Class, ER
  • Çıktı biçimleri: SVG (zengin UI için), ASCII/Unicode (terminal için)
  • Tema sistemi
    • 15 yerleşik tema sunar (tokyo-night, dracula, nord, github-dark vb.)
    • Mono modu: yalnızca arka plan (bg) ve ön plan (fg) olmak üzere iki renkten tüm renkleri otomatik türetir
    • Enriched modu: accent, muted, surface, border gibi isteğe bağlı renklerin tanımlanmasına izin verir
    • CSS özel özellikleri tabanlı gerçek zamanlı geçiş desteği sunar
  • Shiki entegrasyonu
    • VS Code tema renklerini diyagram renklerine otomatik olarak eşler
    • fromShikiTheme() fonksiyonu ile bg, fg, accent vb. değerler çıkarılabilir

Kurulum ve kullanım

  • Kurulum komutu
    • npm install beautiful-mermaid veya bun add beautiful-mermaid, pnpm add beautiful-mermaid
  • SVG render örneği 
    import { renderMermaid } from 'beautiful-mermaid'
const svg = await renderMermaid(`graph TD; A-->B;`)
  • ASCII render örneği 
    import { renderMermaidAscii } from 'beautiful-mermaid'
const ascii = renderMermaidAscii(`graph LR; A --> B --> C`)
  • Tarayıcıda kullanım
    • CDN (unpkg, jsDelivr) üzerinden <script> etiketiyle doğrudan yüklenebilir
    • Global beautifulMermaid nesnesinden renderMermaid, renderMermaidAscii, THEMES vb. öğelere erişilebilir

ASCII çıktısı ve seçenekler

  • Unicode modu (varsayılan) ve saf ASCII modu desteklenir
  • Seçenekler
    • useAscii: ASCII kullanılıp kullanılmayacağı
    • paddingX, paddingY: düğümler arası boşluk
    • boxBorderPadding: düğüm içi boşluk
  • Örnek çıktı 
    ┌───┐     ┌───┐
│ A │────►│ B │
└───┘     └───┘

API özeti

  • renderMermaid(text, options?): Mermaid diyagramını SVG olarak render eder
    • Seçenekler: bg, fg, accent, muted, surface, border, font, transparent
  • renderMermaidAscii(text, options?): ASCII/Unicode metin olarak render eder
  • fromShikiTheme(theme): Shiki temasından renkleri çıkarır
  • THEMES: 15 yerleşik tema nesnesi
  • DEFAULTS: varsayılan renkler (#FFFFFF, #27272A)

Lisans ve üretim

  • MIT lisansı
  • Craft ekibi tarafından geliştirildi
  • ASCII motorunun temeli: Alexander Grooff'un mermaid-ascii projesi

Teknik önemi

  • Yapay zeka kodlama asistanı ortamlarında, diyagramlar terminal veya sohbet arayüzü içinde anında görselleştirilebilir
  • Hafif, hızlı ve bağımlılıksız yapısı sayesinde CLI araçlarında veya sunucu ortamlarında da oldukça kullanışlıdır
  • Tema genişletilebilirliği ve uyumluluğu, geliştirici deneyimini iyileştirir

İlgili okumalar

1 yorum

 
GN⁺ 2026-01-30
Hacker News görüşleri

  • Alexander Grooff’un hazırladığı Go kütüphanesi mermaid-ascii tabanlı proje gerçekten harika görünüyor
    Ancak "start" kenarının render edilmediği bir hata buldum
    Testleri agents.craft.do/mermaid üzerinde yaptım

  • Bu aralar ASCII diyagramlarının neden yeniden ilgi gördüğünü pek anlayamıyorum
    Mermaid ya da PlantUML zaten metin tabanlı; çoğu kullanıcı makineden çok insanın bakması için iyi görünen standart diyagramlar ister
    ASCII, yazdırılabilir karakterlerle sınırlı olduğu için ifade gücü daha düşüktür ve standartlaştırması da zordur

    • Bağlama göre değişir. Örneğin README ya da CLI çıktısı gibi Mermaid render etmenin mümkün olmadığı ortamlarda ASCII, okunabilirlik açısından en iyi seçenektir
    • Kod yorumlarının içine ASCII diyagramlar koyabilirsiniz. Claude Code gibi terminal tabanlı araçlarda da iyi görünür
    • Mesele “ASCII işe yaramaz” değil; metin merkezli iş akışlarında (ör. Org Mode, Git deposu yönetimi) tam tersine kullanışlıdır
      Çünkü görsel dosyaları yönetmek ya da Git LFS gibi karmaşık ayarlar gerektirmez
    • Render edici gerektirmemesi de bir avantajdır. Markdown belgeleri veya kaynak kod içinde doğrudan “render edilmiş” haliyle okunabilir
    • Pek çok geliştirici ve kodlama ajanı ağırlıklı olarak Markdown ve CLI ortamlarını kullandığı için, bu tür bir ASCII yaklaşımı doğaldır

  • Ben ASCII diyagramlarını gerçekten seviyorum
    Terminalde cat ile bakılsın ya da bir web sitesinde render edilsin, her durumda aynı derecede hoş görünmesi cezbedici
    İyi bir monospaced font olduğu sürece görsel olarak da temiz duruyor
    Monodraw adlı ASCII diyagram oluşturma uygulamasını da tavsiye ederim

    • ^Unicode
    • Diyagramı kaynak kodun üst kısmına koyabilmek özellikle hoşuma gidiyor

  • Asıl Mermaid ASCII render edicisi AlexanderGrooff/mermaid-ascii projesinden alınmış
    Bu proje onu TypeScript’e dönüştürmüş ve kendi temasını eklemiş

    • Aslında sadece mermaid-ascii’yi WASM olarak paketlemek de yeterli olabilirdi
      Ana algoritma neredeyse bire bir çevrilmiş; Claude’un bunu TS’ye port etmesi muhtemelen bir saatten bile kısa sürerdi
      Go kodu ile TS kodunu karşılaştırabilirsiniz
    • Atıf için teşekkürler
    • Go tabanlı olduğu için paket yönetimi şakalarına da gerek yok. Bunu hata ayıklayıcıma entegre etmeyi planlıyorum
    • Birisi, yapay zekanın tüm projeyi kopyalayıp sadece adını değiştirmiş olabileceğine dikkat çekti
    • Orijinal bağlantıyı düzelttim. Gönderen kişinin bunu iyi niyetle paylaştığı anlaşılıyor

  • Mermaid ilgi görüyor ama Kroki(kroki.io) çok daha fazla diyagram formatını destekliyor
    BlockDiag, BPMN, C4, D2, DBML, Excalidraw, GraphViz dahil olmak üzere neredeyse tüm metin tabanlı diyagramları kapsıyor
    Benim Markdown editörüm KeenWrite(keenwrite.com), Kroki’yi bir hizmet olarak entegre ediyor; böylece yeni bir format eklendiğinde otomatik olarak kullanılabiliyor
    Mermaid, <foreignObject> kullandığı için çoğu kütüphanede render edilmesi zor

    • MermaidJS ile Kroki’yi karşılaştırmak biraz PDF.js ile Adobe Acrobat’ı karşılaştırmaya benziyor
      MermaidJS web sayfasında hızlı ve yerel olarak çalışırken, Kroki dış bir hizmete bağımlı
      Karmaşık diyagramlara ihtiyacınız yoksa Mermaid daha basit bir tercih
    • Bir zamanlar NetworkX DAG’lerini ASCII olarak render etmek için phart adlı bir araç yapmıştım
      README örneklerinde satranç grafiği dahil çeşitli çıktı örnekleri var
    • İlk başta Kroki’nin tasarımını fazla gölgelendirmeli ve fontları bozulmuş bulup beğenmemiştim ama sonra bunun bir yanlış anlama olduğunu fark ettim
      Yine de Mermaid’in varsayılan stilinin daha temiz olduğunu düşünüyorum
      Bu arada KeenWrite oldukça iyi görünüyor

  • Metni ASCII diyagramlara dönüştüren Diagon diye bir araç da var
    Benim derlediğim metinden diyagrama araçlar listesi da mevcut; ama metinden ASCII’ye dönüştüren araç sayısı çok fazla değil

    • Güzel liste olduğu söylenerek teşekkür edildi

  • Canlı demoyu çalıştırmak için AI ajan platformunu indirmeniz gerekiyor gibi görünüyor
    Kurulum yapmadan hemen denemek isterdim, bu mümkün olmayınca biraz hayal kırıklığı oldu

    • Geliştiriciler GitHub Pages tabanlı, yalnızca istemci tarafında çalışan bir demo hazırlasa iyi olur
      Projenin yapısı buna fazlasıyla uygun görünüyor

  • “Subgraph Direction Override” diye bir özellik var; bu sayede alt grafiğin yönü farklı ayarlanabiliyor
    Bununla, Mermaid’in desteklemediği swim lane diyagramları taklit edilebiliyor

  • Benim yaptığım Selkie, Mermaid ayrıştırıcısını ve render edicisini Rust ile tamamen uygulayan deneysel bir proje
    Claude Code ile ne kadar ileri gidilebildiğini test etmek için başlamıştım ve sonuç şaşırtıcıydı
    Playground üzerinden doğrudan çalıştırabilirsiniz
    Kitty terminali desteklenirse diyagramlar doğrudan terminale de basılabilir
    Yakında tüm süreci bir blog yazısında paylaşmayı düşünüyorum

  • Bu proje gerçekten harika ve Claude Code ile sinerjisi de etkileyici
    Ben de benzer bir proje yaptım ama ASCII yerine etkileşimli kod keşfi üzerine odaklandım
    İnsanların anlamasını kolaylaştıracak şekilde tasarladım, D2 kullandım ve Mermaid desteği de yolda
    İnsan için etkileşimliliğin mi daha değerli olduğu, yoksa ajan bağlamının mı daha önemli olduğu konusunda görüş duymak isterim
    Proje bağlantısı