Cara membuka berkas .mmd

Berkas .mmd adalah berkas teks biasa yang berisi sebuah diagram Mermaid. Ia bukan gambar dan bukan format biner — Anda bisa membukanya dengan penyunting teks apa pun dan membacanya. Untuk melihatnya sebagai diagram, jatuhkan berkas itu ke bingkai di bawah. Ia digambar di peramban Anda sendiri dan tidak ada apa pun yang menuju server mana pun.

Jatuhkan berkas .mmd Anda di sini

Menerima juga .mermaid, .md, dan .txt. Berkasnya dibaca di peramban dan tidak pernah dikirim.

Apa itu berkas .mmd

Mermaid adalah sintaks berbasis teks untuk diagram. Anda menguraikan diagramnya dengan kata-kata dan mesinnya menggambarkannya — persis seperti Markdown menguraikan pemformatan dan mesinnya menghasilkan halaman. Berkas .mmd berisi teks itu dan tidak ada yang lain: tanpa gaya, tanpa data gambar, tanpa metadata.

Di situlah seluruh alasan keberadaan format ini. Karena berupa teks, diagramnya bisa tinggal di repositori Git berdampingan dengan kode yang diuraikannya, dan sebuah perubahan muncul sebagai diff yang terbaca alih-alih sebagai berkas biner yang tergantikan. Ini sebuah berkas .mmd yang lengkap dan sah:

penerapan.mmd — seluruh berkas, enam baris
flowchart LR
    Commit[Push ke main] --> Build[Jalankan pengujian]
    Build -->|berhasil| Deploy[Terapkan ke produksi]
    Build -->|gagal| Beritahu[Beri tahu penulisnya]
    Deploy --> UjiCepat[Uji asap]
    UjiCepat --> Selesai[Rilis selesai]

Berkas .mmd dibuka dengan apa

Singkatnya: hampir tidak ada yang membuka berkas .mmd dengan klik ganda, karena ekstensinya tidak terikat pada aplikasi mana pun. Yang benar-benar Anda perlukan adalah sesuatu yang bisa menggambar Mermaid. Berikut yang sudah saya uji dan tempat-tempat yang tidak berhasil.

Situs iniMembuka

Menggambar berkasnya seketika

Jatuhkan berkasnya ke bingkai di atas dan Anda langsung mendapat diagramnya. Tidak ada langkah unggah: berkasnya dibaca di peramban lewat File API lalu digambar secara lokal, yang juga berlaku untuk diagram yang tidak boleh Anda keluarkan.

Kalau Anda ingin mengubah diagramnya dan bukan sekadar melihatnya, pakailah tautan di bawah pratinjau untuk membukanya di editor.

Penyunting teks apa punMembuka

Menampilkan sumbernya, bukan diagramnya

Notepad, Notepad++, vim — apa saja. Berkas .mmd adalah teks UTF-8, jadi sumbernya langsung terlihat. Diagramnya tidak akan terlihat, dan tidak ada yang rusak — memang tidak ada gambar di dalam berkasnya untuk ditampilkan.

Ini cara tercepat memeriksa apakah berkas yang dikirim orang benar-benar Mermaid: bukalah dan lihat apakah baris pertama yang tidak kosong berupa kata kunci diagram seperti flowchart, sequenceDiagram, classDiagram, stateDiagram-v2, erDiagram, atau gantt.

GitHubTidak membuka

Menggambar blok ```mermaid di Markdown, tetapi tidak menggambar berkas .mmd

GitHub menggambar Mermaid di dalam blok kode berpagar. Dokumentasinya menyebutkan persis di mana saja: issue, Discussions, pull request, wiki, dan berkas Markdown. Berkas .mmd yang berdiri sendiri tidak ada dalam daftar itu, dan membukanya di penjelajah berkas repositori hanya memperlihatkan teks sumbernya.

Jadi kalau Anda ingin diagramnya terlihat di GitHub, ia harus berada dalam blok ```mermaid di dalam berkas .md, bukan di dalam .mmd tersendiri. Menyimpan .mmd sebagai sumber lalu mengulang isi yang sama di README adalah penggandaan yang lazim dan masuk akal.

GitLabTidak membuka

Menggambar blok ```mermaid, tetapi tidak menggambar berkas .mmd, dan pada Mermaid yang lebih tua

Polanya sama dengan GitHub: Mermaid digambar di dalam blok berpagar pada Markdown, issue, merge request, dan wiki, tetapi tidak di mana pun tertulis bahwa berkas .mmd yang berdiri sendiri akan digambar.

Ada hal kedua yang layak diketahui, karena benar-benar menimbulkan kebingungan. GitLab.com menyatakan mendukung Mermaid versi 10. Situs ini berjalan pada 11.12.2. Sintaks yang ditambahkan setelah versi 10 tergambar di sini dan tumbang di sana — dan biasanya itulah yang menjelaskan «di peramban jalan, tapi di GitLab kami tidak». Pada GitLab yang dipasang sendiri ada jebakan ketiga: ketika tajuk Cross-Origin-Resource-Policy disetel ke same-site atau same-origin, diagram Mermaid tumbang tanpa suara — tanpa kesalahan dan tanpa diagram.

.mmd, .mermaid, dan .md

.mmd dan .mermaid itu sama. Keduanya hanya berisi sumber Mermaid, dan semua perkakas yang saya tahu yang menerima yang satu juga menerima yang lain. .mmd lebih pendek dan lebih umum; perkakas baris perintah resminya memakainya sebagai bawaan. Pilih salah satu dan pertahankan dalam satu proyek — pilihan itu tidak berakibat teknis apa pun.

.md berbeda jenisnya. Berkas Markdown adalah dokumen yang bisa memuat diagram Mermaid, dibungkus dalam blok yang diawali tiga tanda petik terbalik dan kata mermaid. Diagramnya adalah sepotong bagian di dalam teks yang lebih besar.

Perbedaan itu adalah penyebab paling sering sebuah berkas tidak tergambar, dan ia bekerja ke dua arah. Tempel isi berkas .md ke penampil Mermaid dan ia tumbang, sebab baris pagarnya bukan sintaks Mermaid. Simpan diagram Mermaid telanjang ke berkas .md tanpa pagar dan GitHub menampilkannya sebagai satu paragraf teks. Aturannya sederhana: berkas .mmd harus diawali kata kunci diagram, dan berkas .md harus menaruh diagramnya di dalam blok berpagar.

Penampil ini menerima .mmd, .mermaid, .md, dan .txt, tetapi memperlakukan segala yang dibacanya sebagai Mermaid mentah. Kalau Anda menjatuhkan Markdown yang ada tulisannya di sekeliling diagram, buanglah dulu segala yang bukan diagram.

Tidak tergambar — sebenarnya apa yang salah

Pesan kesalahan Mermaid tepat tetapi tidak ramah. Satu trik yang manjur adalah membaca bagian paling akhirnya saja: setelah `got`, Mermaid menyebut token tempat ia tersangkut, dan token itu menunjukkan masalahnya jauh lebih baik daripada nomor baris. Setiap kasus di bawah saya reproduksi pada mermaid 11.12.2: versi yang salah memang tumbang, versi yang diperbaiki memang tergambar.

Yang Anda lihat

No diagram type detected matching given configuration for text: ```mermaid

Mengapa

Anda menyalin diagramnya dari berkas Markdown atau dari sebuah obrolan dan ikut membawa pagarnya. Tiga tanda petik terbalik itu Markdown, bukan Mermaid, jadi penguraiannya tidak pernah sampai ke diagramnya.

Solusi

Buang baris pembuka ```mermaid dan baris penutup ```. Berkasnya harus diawali kata kunci diagram.

Salah
```mermaid
flowchart TD
    A[Mulai] --> B[Selesai]
```
Benar
flowchart TD
    A[Mulai] --> B[Selesai]

Yang Anda lihat

Parse error, pesannya berakhir dengan: got 'PS'

Kesalahannya berakhir dengan: got 'PS'

Mengapa

Ada kurung buka di dalam label simpul. Dalam Mermaid, tanda kurung adalah sintaks bentuk — A(teks) berarti simpul bersudut tumpul — jadi kurung telanjang di dalam kurung siku terbaca sebagai awal sebuah bentuk.

Solusi

Bungkus labelnya dengan tanda kutip. Semua di dalam tanda kutip diperlakukan sebagai teks, termasuk tanda kurung.

Salah
flowchart TD
    A[Panggil tagih(pesanan)] --> B[Selesai]
Benar
flowchart TD
    A["Panggil tagih(pesanan)"] --> B[Selesai]

Yang Anda lihat

Parse error pada baris tempat Anda memberi nama simpul

Mengapa

Pengenal simpulnya mengandung spasi. Dalam bahasa Indonesia ini kesalahan yang paling mudah dibuat, karena nama yang wajar terdiri atas beberapa kata: «layanan autentikasi», «basis data». Pengenal adalah token sebelum panah, dan spasi memotongnya sehingga tersisa kata yang tidak punya tempat.

Solusi

Beri simpul itu pengenal satu kata dan taruh teks yang enak dibaca di label. Merangkaikan katanya juga boleh, asal tanpa spasi.

Salah
flowchart TD
    layanan autentikasi --> basis data
Benar
flowchart TD
    auth[Layanan autentikasi] --> db[Basis data]

Yang Anda lihat

Parse error, pesannya berakhir dengan: got 'STR'

Kesalahannya berakhir dengan: got 'STR'

Mengapa

Ada tanda kutip ganda lurus di dalam label simpul. Penguraiannya menganggapnya awal sebuah string, lalu menemui kurung siku label di tempat ia menunggu tanda kutip penutup.

Solusi

Bungkus seluruh labelnya dengan tanda kutip lurus lalu pakai tanda kutip tunggal di dalamnya, atau tulis karakternya sebagai entitas HTML #quot;.

Salah
flowchart TD
    A[Dia bilang "setuju"] --> B[Selesai]
Benar
flowchart TD
    A["Dia bilang 'setuju'"] --> B[Selesai]

Yang Anda lihat

Parse error, pesannya berakhir dengan: got 'end'

Kesalahannya berakhir dengan: got 'end'

Mengapa

Anda memakai end sebagai pengenal simpul. Huruf kecil end menutup sebuah subgraf, jadi penguraiannya melihat akhir blok di tempat ia menunggu simpul. Ini sering terjadi: mengikuti contoh berbahasa Inggris, simpul terakhir jadi bernama end walaupun sisanya berbahasa Indonesia.

Solusi

Tulis dengan huruf besar atau beri simpul itu pengenal lain lalu pindahkan katanya ke label. `Selesai` tidak menimbulkan masalah.

Salah
flowchart TD
    A[Mulai] --> end
Benar
flowchart TD
    A[Mulai] --> Selesai[Sudah selesai]

Yang Anda lihat

Tergambar, tetapi di diagram keadaan satu keadaan menjadi beberapa kotak

Mengapa

Ada spasi di dalam pengenal keadaan. Berbeda dari diagram alir, diagram keadaan tidak protes: ia membuat kotak terpisah untuk setiap kata lalu menggambarnya tanpa berkedip. Terukur — `[*] --> Menunggu pembayaran` menghasilkan dua keadaan, `Menunggu` dan `pembayaran`, dan hanya yang pertama tersambung ke panah. Dalam bahasa Indonesia hampir tidak ada nama keadaan yang muat dalam satu kata, jadi ini terjadi terus-menerus tanpa isyarat apa pun.

Solusi

Deklarasikan keadaannya dengan `state "Label" as id` lalu rujuk hanya lewat pengenalnya.

Salah
stateDiagram-v2
    [*] --> Menunggu pembayaran
    Menunggu pembayaran --> Ditutup
Benar
stateDiagram-v2
    state "Menunggu pembayaran" as menungguBayar
    [*] --> menungguBayar
    menungguBayar --> Ditutup

Yang Anda lihat

Tergambar, tetapi diagram ER punya entitas yang tidak Anda tulis

Mengapa

Label relasinya mengandung spasi dan tidak diberi tanda kutip. Inilah jebakan yang paling mengganggu dalam bahasa Indonesia, karena ungkapan relasi kita terdiri atas beberapa kata: «milik dari», «muncul dalam». Mermaid tidak melaporkan kesalahan: ia memotong labelnya pada spasi pertama dan mengubah setiap kata sisanya menjadi entitas kosong.

Solusi

Beri tanda kutip pada setiap label relasi yang mengandung spasi. Dalam bahasa Indonesia praktis semuanya.

Salah
erDiagram
    PELANGGAN ||--o{ PESANAN : milik dari
Benar
erDiagram
    PELANGGAN ||--o{ PESANAN : "milik dari"

Yang Anda lihat

No diagram type detected matching given configuration for text: sequencediagram

Mengapa

Kata kunci diagramnya salah eja atau salah huruf besar-kecil. Kata kunci Mermaid peka huruf besar-kecil: sequenceDiagram jalan, sequencediagram tidak. Begitu pula stateDiagram-v2 dan erDiagram.

Solusi

Perbaiki huruf besar-kecilnya. Perhatikan graph masih diterima sebagai alias lama flowchart, jadi sintaks kuno itu bukan masalah Anda.

Salah
sequencediagram
    Klien->>API: Halo
Benar
sequenceDiagram
    Klien->>API: Halo

Yang Anda lihat

Parse error pada label garis penghubung di antara garis tegak

Mengapa

Ada tanda kurung di dalam label garis penghubung. Label |...| tunduk pada batasan yang sama dengan label simpul: di sana pun tanda kurung adalah sintaks, bukan teks.

Solusi

Bungkus label garis penghubungnya dengan tanda kutip.

Salah
flowchart TD
    A -->|ya (selalu)| B
Benar
flowchart TD
    A -->|"ya (selalu)"| B

Yang Anda lihat

Parse error yang menunjuk baris terakhir diagram

Mengapa

Ada blok yang dibuka dan tidak pernah ditutup: alt, opt, loop, par, dan subgraph masing-masing menuntut end-nya sendiri. Mermaid melaporkan kesalahan di tempat masukannya habis, jadi nomor barisnya menunjuk akhir berkas dan bukan blok yang menganga.

Solusi

Hitung blok yang dibuka dan end yang sudah Anda tulis. Kalau kesalahannya menunjuk baris terakhir, hampir selalu inilah sebabnya.

Salah
sequenceDiagram
    Klien->>API: Permintaan
    alt Semua beres
        API-->>Klien: OK
Benar
sequenceDiagram
    Klien->>API: Permintaan
    alt Semua beres
        API-->>Klien: OK
    end

Yang Anda lihat

Lexical error on line 1. Unrecognized text.

Mengapa

Arah yang tidak sah setelah kata kunci diagram. Diagram alir menerima TB, TD, BT, LR, dan RL, tidak lebih; salah ketik akan gugur pada analisis leksikal sebelum satu simpul pun terbaca.

Solusi

Pakai salah satu dari lima arah yang sah. TD dan LR menutupi hampir semua kasus.

Salah
flowchart XY
    A --> B
Benar
flowchart TD
    A --> B

Yang Anda lihat

Di sini tergambar, di GitLab, Confluence, atau perkakas lama tidak

Mengapa

Selisih versi. Penampil ini berjalan pada Mermaid 11.12.2; GitLab.com mendokumentasikan versi 10, dan wiki yang dipasang sendiri bisa tertinggal bertahun-tahun. Sintaks yang diperkenalkan setelah versi perkakas yang satunya akan terurai di sini dan tumbang di sana.

Solusi

Tanyakan versinya kepada mesin yang satunya. Menulis satu kata info di dalam diagram membuat Mermaid menggambar nomor versinya sendiri, yang lebih cepat daripada membaca catatan perubahan.

Benar
info

Ada satu hal yang justru patut disebut karena ia tidak menjadi masalah di sini: pengodean karakter. Bahasa Indonesia ditulis seluruhnya dengan huruf dalam rentang ASCII, tanpa tanda diakritik, jadi berkas .mmd berbahasa Indonesia praktis kebal terhadap kekacauan pengodean yang menimpa bahasa lain — berkas yang disimpan dalam ISO-8859-1, Windows-1252, atau UTF-8 akan terbaca sama saja. Situs ini membaca berkas sebagai UTF-8 dan membuang penanda BOM bila ada. Satu-satunya yang perlu diperhatikan adalah kalau Anda memasukkan kutipan berbahasa asing ke dalam label; di situlah pengodean bisa mulai berpengaruh.

Dan ada satu hal lagi yang tidak menghasilkan kesalahan apa pun: pada GitLab yang dipasang sendiri, tajuk Cross-Origin-Resource-Policy yang disetel ke same-site atau same-origin membuat diagram Mermaid tumbang tanpa suara. Tidak ada pesan, tidak ada diagram, tidak ada apa-apa di halaman. Kalau sebuah diagram tergambar di mana-mana kecuali pada satu pemasangan sendiri, di situlah tempat yang harus dilihat.

Mengubah ke PNG, SVG, atau PDF

Buka berkasnya di editor lalu pakai tombol ekspor. SVG mempertahankan diagramnya sebagai teks vektor, jadi ia tetap tajam pada ukuran berapa pun dan labelnya bisa diseleksi serta dicari — itu pilihan yang tepat untuk dokumentasi dan untuk segala hal yang mungkin diekspor ulang nanti. PNG adalah peta bit, yang di sini diekspor pada dua sampai tiga kali ukuran tampilan agar tahan di layar berkerapatan tinggi; pakailah di tempat yang tidak menerima SVG, yang dalam praktiknya berarti sebagian besar aplikasi perpesanan dan sebagian wiki.

Tombol PDF tidak ada, dan saya lebih suka menuliskannya daripada berpura-pura. Jalan yang bisa ditempuh adalah mengekspor SVG lalu menyisipkannya ke dokumen yang memang sedang Anda tulis, atau mencetak halaman ini ke PDF dari peramban. SVG vektor yang disisipkan ke dalam PDF tetap berupa vektor.

Untuk segala yang berulang — sebuah langkah build, sekumpulan berkas, sebuah pre-commit hook — sudah ada mesin baris perintah resmi @mermaid-js/mermaid-cli: ia mengambil berkas .mmd yang sama dan menulis gambarnya langsung, tanpa peramban.

Pertanyaan yang sering diajukan

Bagaimana membuka berkas .mmd secara daring?
Jatuhkan ke bingkai di bagian atas halaman ini. Ia digambar di peramban Anda, tanpa unggahan dan tanpa akun. Anda juga bisa membuka editornya lalu menyeret berkasnya ke panel pratinjau.
Program apa yang membuka berkas .mmd?
Sumbernya bisa ditampilkan penyunting teks apa pun, sebab berkasnya teks biasa. Untuk melihat diagramnya Anda perlu sesuatu yang menggambar Mermaid: situs ini, editor di sini, atau perkakas baris perintah mermaid-cli. Tidak ada aplikasi desktop yang memiliki ekstensi .mmd.
Apakah berkas .mmd sama dengan .mermaid?
Ya. Kedua ekstensi itu berisi hal yang sama persis dan bisa dipertukarkan. .mmd lebih umum dan itulah yang dipakai perkakas baris perintah resmi sebagai bawaan.
Mengapa berkas .mmd saya tidak tergambar di GitHub?
GitHub hanya menggambar Mermaid di dalam blok berpagar ```mermaid pada berkas Markdown, issue, Discussions, pull request, dan wiki. Berkas .mmd yang berdiri sendiri ditampilkan sebagai teks sumber. Taruh diagram yang sama di dalam blok berpagar pada berkas .md agar terlihat di GitHub.
Bisakah saya membuka .mmd tanpa memasang apa pun?
Bisa — untuk itulah situs ini ada. Penggambarannya berjalan sebagai JavaScript di peramban Anda, jadi tidak ada yang perlu dipasang dan berkasnya tidak pernah meninggalkan komputer Anda.
Diagram saya bermasalah dan saya tidak menemukan letak salahnya
Dalam bahasa Indonesia, penyebab tersering adalah spasi di dalam sebuah pengenal. Pada diagram alir itu langsung berupa Parse error, tetapi pada diagram keadaan ia diam-diam memecah satu keadaan menjadi satu kotak per kata, dan pada label relasi ER ia memotong labelnya lalu membuat entitas hantu. Nama proses kita hampir selalu terdiri atas beberapa kata, jadi curigai itu lebih dulu.
Apakah pengodean karakter bisa menjadi masalah?
Untuk bahasa Indonesia hampir tidak pernah, dan itu kabar baik. Bahasa Indonesia ditulis seluruhnya dengan huruf dalam rentang ASCII, jadi berkasnya terbaca sama saja entah disimpan sebagai UTF-8, ISO-8859-1, atau Windows-1252. Situs ini membaca berkas sebagai UTF-8 dan menangani penanda BOM tanpa masalah.
Di sini jalan, di wiki kami tidak. Kenapa?
Hampir selalu karena selisih versi. Penampil ini berjalan pada Mermaid 11.12.2, sedangkan banyak wiki berjalan pada versi yang lebih tua — GitLab.com mendokumentasikan versi 10. Tulis kata info di dalam sebuah diagram pada sistem yang satunya agar ia mencetak versi yang dipakainya.

Jenis diagram yang bisa Anda buka di sini

Ditulis oleh Dominik Malsch · Terakhir diperbarui:

Buka editor →