Diagram teknis sering kali menjadi basi karena pengeditannya memerlukan pencarian file desain asli, membuka aplikasi terpisah, dan mengekspor gambar lain.Mermaid mengambil pendekatan yang berbeda: diagram didefinisikan sebagai teks dan disimpan di samping dokumentasi.
Untuk menambahkan Mermaid ke Markdown, tempatkan definisi diagram di dalam blok kode berpagar dengan mermaid pengenal bahasa.Gunakan Pratinjau diagram Mermaid untuk merender sintaks secara lokal, memperbaiki kesalahan, menyalin pagar Markdown lengkap, atau mengunduh SVG.
Panduan ini dimulai dengan diagram alur kecil dan dilanjutkan ke diagram urutan, kelas, Gantt, peta pikiran, dan hubungan entitas.
Mermaid dalam 30 Detik
Blok dasar Mermaid terlihat seperti ini:
```mermaid
flowchart LR
Draft --> Review
Review --> Publish
```
Pagar pembuka memberi tahu penyaji yang kompatibel bahwa kontennya adalah sintaksis Mermaid. flowchart LR memilih diagram alur yang disusun dari kiri ke kanan.Baris yang tersisa mendefinisikan node dan koneksi.
Jika tujuan tidak mendukung Mermaid, pembaca biasanya akan melihat blok kode, bukan diagram.Penggantian tersebut mempertahankan sumbernya, namun bukan pengganti pemeriksaan kompatibilitas sebelum dipublikasikan.
Mengapa Menggunakan Diagram Berbasis Teks?
Mermaid sangat berguna ketika diagram:
- termasuk dalam dokumentasi yang dikontrol versi;
- perubahan seiring dengan kode atau prosedur;
- membutuhkan perbedaan permintaan tarik yang berarti;
- menggunakan bentuk dan hubungan standar;
- harus dapat diedit tanpa file desain berpemilik;
- harus dibuat ulang dalam tema terang dan gelap.
Kurang cocok untuk ilustrasi detail, tata letak piksel sempurna, anotasi tangan bebas, atau desain visual yang memerlukan penempatan manual presisi.Jika demikian, gunakan alat menggambar dan ekspor SVG atau gambar yang dapat diakses.
Contoh 1: Diagram Alir
Diagram alur menjelaskan proses, keputusan, atau aturan perutean.
```mermaid
flowchart TD
A[Choose a DOCX file] --> B{File valid?}
B -->|Yes| C[Convert to Markdown]
B -->|No| D[Show an error]
C --> E[Review the output]
E --> F[Copy or download]
```
Sintaks kunci:
TDartinya dari atas ke bawah.LRartinya kiri ke kanan.[Text]membuat node proses persegi panjang.{Text}membuat simpul keputusan.-->membuat koneksi terarah.-->|Label|menambahkan teks ke koneksi.
Gunakan ID node pendek yang stabil seperti A or validate.Simpan label yang terlihat di dalam tanda kurung sehingga mengubah kata-katanya tidak memerlukan perubahan setiap sambungan.
Tambahkan subgraf
Langkah-langkah terkait grup subgraf:
```mermaid
flowchart LR
subgraph Browser
Upload[Choose file] --> Convert[Convert locally]
end
subgraph Output
Preview[Preview Markdown] --> Save[Download file]
end
Convert --> Preview
```
Gunakan subgraf ketika pengelompokan mengkomunikasikan kepemilikan, batasan sistem, atau fase.Jangan menambahkan kotak hanya untuk hiasan.
Contoh 2: Diagram Urutan
Diagram urutan menunjukkan interaksi dalam urutan waktu.Mereka berfungsi dengan baik untuk panggilan API, autentikasi, alur kerja browser, dan sistem berbasis peristiwa.
```mermaid
sequenceDiagram
autonumber
actor User
participant Browser
participant Converter
User->>Browser: Select DOCX file
Browser->>Converter: Pass local file data
Converter-->>Browser: Return Markdown
Browser-->>User: Show editable preview
```
Panah umum:
->>mengirimkan pesan yang solid.-->>mengirimkan respons putus-putus.participantmendeklarasikan sistem atau layanan.actormenyatakan peran manusia atau eksternal.autonumbermemberi label interaksi secara berurutan.
Fokus pada satu skenario.Diagram urutan yang mencoba menunjukkan setiap alternatif dan setiap fungsi internal menjadi lebih sulit untuk dipahami daripada kode.
Tunjukkan jalur alternatif
```mermaid
sequenceDiagram
participant Client
participant API
Client->>API: POST /documents
alt Valid request
API-->>Client: 201 Created
else Invalid request
API-->>Client: 400 Bad Request
end
```
Penggunaan alt, else, dan end untuk cabang yang bermakna.Jika cabang memerlukan beberapa halaman penjelasan, tautan ke prosa di bawah diagram.
Contoh 3: Diagram Kelas
Diagram kelas menjelaskan tipe, properti, operasi, pewarisan, dan hubungan.
```mermaid
classDiagram
class Document {
+String name
+String content
+convert()
}
class MarkdownDocument {
+String frontmatter
+render()
}
Document <|-- MarkdownDocument
```
Contoh ini menyatakan bahwa MarkdownDocument mewarisi dari Document.Gunakan diagram kelas untuk model konseptual, bukan sebagai pengganti otomatis untuk dokumentasi referensi lengkap API.
Diagram kelas yang baik menghilangkan detail yang tidak membantu pembaca memahami desain.Menampilkan setiap bidang pribadi dapat mengubah diagram menjadi versi kode sumber yang kurang mudah dicari.
Contoh 4: Bagan Gantt
Bagan Gantt menunjukkan tugas sepanjang waktu.Mereka berguna untuk rencana rilis, migrasi, dan proyek dokumentasi.
```mermaid
gantt
title Documentation migration
dateFormat YYYY-MM-DD
section Preparation
Inventory content :done, inventory, 2026-11-03, 3d
Define templates :done, templates, after inventory, 2d
section Migration
Convert documents :active, convert, 2026-11-08, 7d
Editorial review :review, after convert, 5d
section Publish
Final validation :validate, after review, 2d
```
Jaga tanggal tetap eksplisit dan gunakan ID tugas ketika satu tugas bergantung pada tugas lainnya.Ingatlah bahwa diagram yang disimpan dalam dokumentasi tidak akan diperbarui sendiri ketika jadwal proyek sebenarnya berubah.Tetapkan kepemilikan untuk menjaganya tetap terkini.
Contoh 5: Peta Pikiran
Peta pikiran mengatur ide-ide seputar topik sentral.
```mermaid
mindmap
root((Markdown quality))
Structure
Headings
Lists
Tables
Accessibility
Alt text
Link text
Reading order
Publishing
GitHub
Obsidian
Documentation site
```
Peta pikiran paling efektif selama perencanaan atau sebagai gambaran umum tingkat tinggi.Mereka kurang berguna untuk hubungan yang tepat karena struktur pohon dapat menyiratkan hierarki dimana konsep sebenarnya tumpang tindih.
Contoh 6: Diagram Hubungan Entitas
Diagram ER menggambarkan entitas data dan hubungannya.
```mermaid
erDiagram
AUTHOR ||--o{ DOCUMENT : writes
DOCUMENT ||--o{ REVISION : contains
DOCUMENT }o--o{ TAG : uses
AUTHOR {
string id
string name
}
DOCUMENT {
string id
string title
datetime published_at
}
```
Gunakan diagram ER untuk menjelaskan model dan skema atau file migrasi untuk menentukan implementasi.Diagram mungkin menghilangkan indeks, batasan, dan bidang yang tidak relevan dengan penjelasan saat ini.
Pratinjau Mermaid Sebelum Diterbitkan
Menulis diagram secara langsung dalam dokumen Markdown yang panjang membuat kesalahan sintaksis sulit diisolasi.Putaran pratinjau terfokus lebih cepat:
- Buka Pratinjau diagram Mermaid.
- Tempelkan definisi diagram saja, tanpa pagar kode bagian luar.
- Render diagramnya.
- Baca kesalahan sintaksis apa pun dan perbaiki area referensi.
- Salin Markdown yang dipagari.
- Unduh SVG ketika tujuan membutuhkan aset statis.
- Uji Markdown terakhir di platform sebenarnya.
Pratinjau ditampilkan di browser Anda dengan konfigurasi keamanan yang ketat.Callback diagram dan perilaku interaktif lainnya mungkin dinonaktifkan meskipun instalasi Mermaid lain mengizinkannya.Perilaku konservatif tersebut sesuai untuk alat pratinjau umum.
Kesalahan Umum Mermaid
Jenis diagram tidak ada
Tidak benar:
A --> B
Benar:
flowchart LR
A --> B
Baris pertama mengidentifikasi tata bahasa diagram.
Tanda baca pada label menghentikan penguraian
Kutipan label kompleks:
flowchart LR
A["Parse input: DOCX, HTML, or text"] --> B["Create Markdown"]
Ini khususnya berguna untuk tanda kurung, tanda baca, dan label yang menyerupai sintaksis.
Word yang dicadangkan digunakan secara tidak terduga
Mermaid tata bahasa memiliki kata kunci.Dokumentasi diagram alur resmi secara khusus memperingatkan huruf kecil itu end dapat merusak diagram alur.Gunakan huruf kapital atau tempatkan teks yang terlihat di dalam label simpul yang diberi tanda kutip:
flowchart LR
Start --> Finish["End"]
Pagar kode salah
Pengidentifikasi bahasa dimiliki tepat setelah backticks pembuka:
```mermaid
flowchart LR
A --> B
```
Jangan membuat indentasi seluruh pagar kecuali sintaks Markdown di sekitarnya memerlukannya.
Ia bekerja di satu platform tetapi tidak di platform lain
Mermaid berkembang, dan platform dapat menggunakan penyaji, versi, pengaturan keamanan, dan jenis diagram yang berbeda.Fitur sintaksis yang didukung oleh rilis terbaru Mermaid mungkin gagal pada platform yang menggunakan implementasi lain atau versi yang lebih lama.
Lebih menyukai sintaksis yang didukung secara luas untuk dokumen yang berpindah antar platform.Uji bentuk, tema, arahan, dan tipe diagram yang lebih baru di setiap tujuan yang diperlukan.
Kompatibilitas Platform
Kompatibilitas harus diuji daripada diasumsikan:
| Platform | Pendekatan terdokumentasi saat ini | Catatan penting |
|---|---|---|
| GitHub | Gunakan yang berpagar mermaid block | GitHub dokumen yang dirender dalam file Markdown, terbitan, diskusi, permintaan penarikan, dan wiki |
| GitLab | Gunakan blok kode Mermaid di GitLab Flavored Markdown | GitLab mendokumentasikan versi Mermaid yang didukungnya;instalasi yang dikelola sendiri mungkin berbeda |
| Obsidian | Gunakan yang berpagar mermaid blok dalam catatan | Obsidian dan fitur yang didukung dapat berubah antar rilis |
| Bahan untuk MkDocs | Konfigurasikan pagar khusus Mermaid | Integrasi tema asli memerlukan dokumentasi pymdownx.superfences configuration |
| Pengurai Markdown generik | Seringkali hanya menampilkan kode | Mermaid rendering biasanya memerlukan integrasi JavaScript atau plugin build |
Periksa dokumentasi resmi terkini sebelum mengandalkan fitur yang lebih baru:
- GitHub: Membuat diagram
- GitLab Rasa Markdown
- Obsidian: Sintaks pemformatan tingkat lanjut
- Bahan untuk MkDocs: Diagram
- Mermaid
Untuk situs dokumentasi yang Anda kendalikan, sematkan versi ketergantungan Mermaid dan uji peningkatan.Jika tidak, sedikit perubahan sintaksis dapat mengubah diagram di seluruh situs.
Mermaid dan Aksesibilitas
SVG yang dirender tidak secara otomatis mengkomunikasikan maknanya kepada setiap pembaca.Perlakukan diagram sebagai ringkasan visual dan berikan penjelasan yang setara dalam prosa terdekat.
Untuk diagram alur konversi sebelumnya, tambahkan teks seperti:
Pengguna memilih file DOCX.File yang valid dikonversi secara lokal dan ditampilkan untuk ditinjau;file yang tidak valid menghasilkan kesalahan.Pengguna kemudian dapat menyalin atau mengunduh Markdown yang telah ditinjau.
Praktik aksesibilitas:
- perkenalkan apa yang dijelaskan diagram;
- merangkum kesimpulan setelah diagram yang rumit;
- tidak menyandikan makna hanya dengan warna;
- menggunakan label yang mudah dibaca, bukan singkatan internal;
- mempertahankan kontras yang memadai dalam tema terang dan gelap;
- hindari diagram yang memerlukan interaksi mouse yang tepat;
- memberikan alternatif teks atau tabel untuk informasi penting;
- ekspor SVG dengan hati-hati ketika file statis harus memiliki nama yang dapat diakses.
Kode sumber berguna bagi penulis, tetapi belum tentu merupakan alternatif teks yang baik bagi pembaca.
Merancang Diagram yang Tetap Dapat Dibaca
Pertahankan satu tujuan per diagram
Diagram harus menjawab pertanyaan seperti “Apa yang terjadi setelah permintaan gagal?”atau “Layanan mana yang memiliki setiap penyimpanan data?”Jika ia mencoba menjelaskan keseluruhan sistem, pisahkanlah.
Lebih menyukai label pendek
Masukkan penjelasan rinci dalam bentuk prosa.Label panjang memaksa simpul sempit, pembungkusan garis yang canggung, dan diagram besar di layar seluler.
Gunakan arahan dengan sengaja
Aliran kiri ke kanan berfungsi dengan baik untuk proses pendek dan jalur permintaan.Aliran dari atas ke bawah sering kali lebih cocok untuk layar sempit.Pratinjau keduanya sebelum melakukan.
Batasi gaya visual
Warna khusus dapat bertentangan dengan mode gelap atau tema platform.Mulailah dengan default penyaji.Tambahkan gaya hanya jika gaya tersebut menyampaikan makna dan tetap dapat dibaca di semua tema yang diperlukan.
Dekatkan sumber dengan penjelasannya
Simpan blok Mermaid dalam file Markdown yang sama bila memungkinkan.Hal itu membuat prosa dan diagram berubah bersamaan dalam satu ulasan.
Mermaid vs Gambar Statis
Pilih Mermaid ketika:
- diagram sering berubah;
- perbedaan sumber sangat berharga;
- tata letak menggunakan tipe diagram standar;
- platform penerbitan merender Mermaid dengan andal.
Pilih SVG atau PNG ketika:
- desain memerlukan tata letak manual yang tepat;
- tujuan tidak merender Mermaid;
- tampilan persisnya harus tetap;
- berbagi eksternal memerlukan aset mandiri.
Hibrida yang berguna adalah mempertahankan sumber Mermaid dan mengekspor SVG untuk tujuan yang tidak dapat merendernya.Simpan sumber di samping aset yang diekspor dan dokumentasikan cara membuatnya kembali.
Penggunaan Markdown ke gambar untuk konten Markdown yang dapat dibagikan, atau unduh SVG langsung dari Pratinjau diagram Mermaid ketika diagram itu sendiri adalah aset.
FAQ
Apakah Mermaid bagian dari standar Markdown?
Tidak. Berpagar mermaid adalah ekstensi yang dikenali oleh aplikasi dan sistem pembangunan yang kompatibel.Parser Markdown dasar dapat menjadikannya sebagai kode biasa.
Apakah GitHub merender diagram Mermaid?
Ya.Dokumentasi GitHub menjelaskan rendering Mermaid dalam file Markdown dan beberapa permukaan kolaborasi.Uji sintaksis yang lebih baru karena GitHub mengontrol penyaji dan pengaturan keamanan yang diterapkan.
Bisakah saya menggunakan Mermaid di Obsidian?
Obsidian mendokumentasikan blok diagram berpagar gaya Mermaid dalam catatan.Dukungan fitur dapat berubah seiring dengan perender aplikasi, jadi verifikasi jenis diagram yang rumit atau baru diperkenalkan dalam versi yang Anda instal.
Bisakah Mermaid menggantikan dokumentasi arsitektur?
Tidak. Diagram adalah salah satu tampilan suatu sistem.Pasangkan dengan keputusan, kepemilikan, batasan, perilaku kegagalan, dan tautan ke antarmuka atau skema otoritatif.
Mengapa diagram saya ditampilkan secara berbeda dalam mode gelap?
Platform mungkin menerapkan tema Mermaid, variabel CSS, font, dan latar belakang yang berbeda.Hindari warna-warna yang dikodekan secara keras sampai Anda menguji kedua tema tersebut.
Haruskah saya mengkomit file SVG yang diekspor?
Melakukan SVG ketika tujuan penerbitan memerlukan aset statis atau hasil yang diberikan harus tetap stabil.Simpan juga sumber Mermaid dan proses regenerasi yang terdokumentasi untuk mencegah kedua versi menyimpang.
Apakah Mermaid aman untuk diagram rahasia?
Kerahasiaan bergantung pada alur kerja editor dan penerbitan.Pratinjau WordToMD menampilkan diagram di browser Anda, tetapi memublikasikan Markdown atau SVG ke repositori atau situs mengikuti kontrol akses tujuan tersebut.
Kesimpulan
Mermaid membuat diagram dapat dipelihara karena sumbernya hidup dengan Markdown.Mulailah dengan blok kecil berpagar, pilih jenis diagram yang cocok dengan pertanyaan, pratinjau sintaksisnya, dan uji di perender akhir.Gunakan prosa untuk menjelaskan makna penting dan ekspor SVG ketika suatu tujuan membutuhkan aset statis.
Coba contoh di Pratinjau diagram Mermaid, edit dokumentasi sekitarnya di Markdown Penyunting, dan jaga agar diagram tetap fokus sehingga kontributor di masa mendatang dapat memahami dan memperbaruinya tanpa menggambar ulang seluruh halaman.