Markdown'da Mermaid Diyagramları: Akış Şemaları, Sıralama Diyagramları ve Daha Fazlası

Diyagramlar süreçleri, mimarileri ve zaman çizelgelerini paragraflarca metinden daha iyi anlatır. Ancak onları bir grafik editöründe çizmek; görselleri dışa aktarmak, belgelerin yanında saklamak ve bir şey değiştiğinde her şeyi yeniden çizmek demektir.

Mermaid bu sorunu çözer: diyagramı Markdown dosyanızın içinde birkaç satır metinle tarif edersiniz, önizleyici de onu çizer. Diyagram aynı dosyada yaşar, diff’lerde görünür ve bir cümle kadar kolay güncellenir. GitHub, GitLab, Obsidian, birçok belge oluşturucu ve Markdown Preview Editor Mermaid’i kutudan çıktığı gibi görüntüler.

Mermaid diyagramı nasıl eklenir?

Bir kod bloğu oluşturun ve dilini mermaid olarak belirleyin:

markdown```mermaid
flowchart LR
  A[Yaz] --> B[Önizle]
  B --> C{Hazır mı?}
  C -- evet --> D[Dışa aktar]
  C -- hayır --> A
```

Önizleyici bunu şuna dönüştürür:

İlk satır diyagram türünü belirtir. Sonrasındaki her şey düğümleri ve bağlantıları tanımlar.

Akış şemaları

Akış şemaları en çok kullanılan diyagram türüdür. Yön, anahtar sözcükten sonra gelir: TD veya TB (yukarıdan aşağıya), BT, LR (soldan sağa) ya da RL.

mermaidflowchart TD
  start([Başla]) --> input[/Dosyayı oku/]
  input --> valid{Geçerli mi?}
  valid -- Evet --> save[(Veritabanına kaydet)]
  valid -- Hayır --> error[Hata göster]
  error --> input

Etiketin etrafındaki parantezler düğümün şeklini belirler:

Bağlantılar: --> bir ok, --- oksuz bir çizgi, -.-> noktalı bir ok, ==> ise kalın bir oktur. -- metin --> veya -->|metin| ile etiket ekleyin.

İlgili düğümleri subgraph ile gruplayın:

mermaidflowchart LR
  subgraph Browser
    editor[Düzenleyici] --> preview[Önizleme]
  end
  preview --> export[HTML / PDF]

Sıralama diyagramları

Sıralama diyagramları (sequence diagram), katılımcıların zaman içinde nasıl mesajlaştığını gösterir — API’ler, kimlik doğrulama akışları ve kullanıcı yolculukları için idealdir.

mermaidsequenceDiagram
  participant U as Kullanıcı
  participant A as Uygulama
  participant S as Sunucu
  U->>A: "Giriş yap"a tıklar
  A->>S: POST /login
  S-->>A: 200 OK + token
  A-->>U: Paneli gösterir
  Note over A,S: Token 1 saat sonra geçersiz olur

->> düz bir ok (istek), -->> kesikli bir ok (yanıt) çizer. Note over, Note left of ve Note right of not ekler. Tekrarı ve dallanmayı göstermek için loop, alt/else ve opt bloklarını kullanın.

Gantt şemaları

Gantt şeması bir görev listesini zaman çizelgesine dönüştürür. Görevler bir tarihte ya da başka bir görevden sonra (after) başlayabilir.

mermaidgantt
  title Belgeleme sprinti
  dateFormat YYYY-MM-DD
  section Yazım
  Ana hatlar        :done,   a1, 2026-10-01, 2d
  İlk taslak        :active, a2, after a1, 4d
  section İnceleme
  Akran incelemesi  :        a3, after a2, 3d
  Yayımlama         :milestone, after a3, 0d

Durum diyagramları

Durum diyagramları bir şeyin durumlar arasında nasıl geçiş yaptığını tanımlar — bir sipariş, bir belge, bir arayüz bileşeni.

mermaidstateDiagram-v2
  [*] --> Draft
  Draft --> Review : gönder
  Review --> Draft : değişiklik istendi
  Review --> Published : onayla
  Published --> [*]

Pasta grafikleri

Bütünün paylarını hızlıca göstermek için pasta grafiği dilim başına bir satır alır:

mermaidpie title Belgeleme zamanı nereye gidiyor
  "Yazma" : 45
  "Biçimlendirme" : 15
  "Diyagramları güncel tutma" : 40

Mermaid ayrıca sınıf diyagramlarını, varlık-ilişki diyagramlarını, zihin haritalarını, zaman çizelgelerini, Git grafiklerini, dörtlü (quadrant) grafikleri ve daha fazlasını destekler. Her birinin sözdizimi resmi Mermaid web sitesinde belgelenmiştir.

Okunaklı diyagramlar için ipuçları

• Küçük tutun. 15–20’den fazla düğümü olan bir diyagramı okumak zorlaşır. Onu her fikir için bir tane olmak üzere birkaç diyagrama bölün.
• Yönü bilinçli seçin. LR az adımlı süreçlere uyar; TD ise hiyerarşilere ve uzun akışlara, özellikle dar ekranlarda.
• Kısa kimlikler ve okunaklı etiketler kullanın. Etiketi kimlik olarak kullanmak yerine auth[Oturumu kontrol et] yazın — bağlantılar kısa kalır.
• Özel karakter içeren etiketleri tırnak içine alın: A["Fiyat: $5 (KDV dahil)"].
• Satır başında %% ile yorum ekleyin. Çizim sırasında yok sayılırlar.
• Yazarken önizleyin. Eksik bir ok ya da parantez bütün diyagramı bozar; bu yüzden canlı önizleme sizi pek çok tahminden kurtarır. Markdown Preview Editor’da diyagram siz düzenledikçe yeniden çizilir ve Gelişmiş düzenleyici araç çubuğundaki Mermaid diyagramı düğmesi bir başlangıç şablonu ekler.

Diyagramlı belgeleri paylaşmak

Bir belgeyi HTML veya PDF olarak dışa aktardığınızda diyagramlar görsel olarak eklenir; böylece okuyucunun Mermaid kurmasına gerek kalmaz. Diyagramlarınızın yanındaki formüller için Markdown’da matematik yazımı yazısına bakın; geri kalan her şey için — tablolar, görev listeleri, uyarı kutuları — Markdown kopya kâğıdını el altında tutun.