Snabbstart och referensguide för Mermaid-diagram för utvecklare
Diagram som kod, utan krångel.
Mermaid är ett textbaserat verktyg för diagramskapning, riktat till de som föredrar att skriva diagram framför att dra runt rutor på en canvas. Det använder en Markdown-liknande syntax för att beskriva flödesdiagram, sekvensdiagram, klassdiagram, statmaskiner, tidslinjer, Gantt-diagram, entitetsrelationsdiagram och mer.
För en teknisk blogg är Mermaid ett mycket bra standardval. Diagrammen finns sida vid sida med artikeln, de kan granskas i Git och de är lätta att uppdatera när systemet förändras. Statiska bildbaserade diagram ser fina ut tills den första arkitekturändringen sker. Mermaid-diagram är inte perfekta, men de åldras betydligt bättre.
Denna guide är en praktisk snabbstart och fuskblad för Mermaid, avsedd för utvecklare, tekniska författare och ägare av Hugo-sidor. Den är en del av hubben Dokumentationsverktyg 2026: Markdown, LaTeX, PDF & arbetsflöden för utskrift.
Vad är Mermaid?
Mermaid är en syntax för “diagram som kod”. Du skriver en liten textblock och Mermaid renderar den som ett diagram.
Ett grundläggande Mermaid-diagram ser ut så här:
denna kod:
```mermaid
flowchart TD
A[Skriv Markdown] --> B[Lägg till Mermaid-block]
B --> C[Rendera sidan]
C --> D[Publisera diagram]
```
Ger följande diagram:
Den viktiga idén är enkel: diagramkällan är ren text. Det gör den sökbar, granskbar, portabel och enkel att hålla tillsammans med den dokumentation den förklarar.
Varför använda Mermaid i en teknisk blogg?
Mermaid är användbar när din artikel behöver mer än bara text, men mindre än ett fullvärdigt designtverktyg.
Använd Mermaid när du vill förklara:
- Begäran- och svarsflöden
- Implementeringspipelines
- Tjänstberoenden
- Tillståndstransitioner
- Databasrelationer
- Användarresor
- Byggsteg
- Beslutslogik
- Projektens tidslinjer
Jag skulle inte använda Mermaid för varje visuell bild. Skärmdumpar, handritade arkitekturskisser och polerade marknadsföringsdiagram har fortfarande sin plats. Men för teknisk dokumentation är Mermaid ofta det underhållsbästa alternativet.
Mermaid Snabbstart
Grundläggande Markdown-användning
I Markdown använder du ett inhägnat kodblock med mermaid som språk:
```mermaid
flowchart LR
A[Start] --> B[Process]
B --> C[Klart]
```
Många plattformar förstår detta format direkt. mermaid är en av de speciella språkidentifierarna — tillsammans med diff, geojson och andra — som vissa renderare behandlar som en förstaklass blocktyp snarare än vanlig syntaxmarkering. För en fullständig genomgång av syntax för inhägnade block och supportede språkidentifierare, se guiden Markdown-kodblock. För Hugo beror renderingen på ditt tema eller sidkonfiguration. Mer om det senare.
Testa diagram innan publicering
Den enklaste arbetsflödet är:
- Skriv diagrammet i din Markdown-fil.
- Klistra in det i en Mermaid-liveeditor eller lokal förhandsgranskning.
- Fixa syntaxfel.
- Commita Markdown-källan.
- Kontrollera den slutliga renderade sidan.
Detta undviker det klassiska problemet där ett diagram fungerar i en renderare men kraschar i en annan på grund av en liten syntaxdetalj.
Flödessyntax
Flödesdiagram är den vanligaste typen av Mermaid-diagram. Använd dem för arbetsflöden, algoritmer, beslutsträd och systemsteg.
Grundläggande flödesdiagram
denna kod:
```mermaid
flowchart TD
A[Användaren öppnar webbplatsen] --> B{Är användaren inloggad?}
B -->|Ja| C[Visa instrumentpanel]
B -->|Nej| D[Visa inloggningssida]
```
Ger följande diagram:
Flödesriktningar
Mermaid-flödesdiagram stödjer flera riktningar:
TD - topp till botten
TB - topp till botten
BT - botten till topp
LR - vänster till höger
RL - höger till vänster
Exempel:
denna kod:
```mermaid
flowchart LR
Browser --> CDN
CDN --> WebServer
WebServer --> Database
```
Ger följande diagram:
För blogginlägg är LR ofta lättare att läsa för arkitekturdiagram. För steg-för-steg-processer är TD vanligtvis bättre.
Vanliga nodformer
denna kod:
```mermaid
flowchart TD
A[Rektangel]
B(Rundad rektangel)
C{Beslut}
D((Cirkel))
E[(Databas)]
F[[Subrutin]]
```
Ger följande diagram:
Flödespilar
denna kod:
```mermaid
flowchart LR
A --> B
B --- C
C -.-> D
D ==> E
E -- Etiket --> F
```
Ger följande diagram:
Subgrafer
Använd subgrafer för att gruppera relaterade delar av ett system.
denna kod:
```mermaid
flowchart LR
subgraph Client
Browser
end
subgraph Backend
API
Worker
end
subgraph Storage
DB[(PostgreSQL)]
Cache[(Redis)]
end
Browser --> API
API --> DB
API --> Cache
API --> Worker
```
Ger följande diagram:
Subgrafer är kraftfulla, men använd dem med omtanke. Ett diagram med sex subgrafer och tjugo pilar är oftast ett tecken på att artikeln behöver två mindre diagram.
Sekvensdiagram-syntax
Sekvensdiagram visar kommunikation mellan aktörer eller tjänster över tid.
denna kod:
```mermaid
sequenceDiagram
participant User
participant App
participant API
participant DB
User->>App: Klicka på inloggning
App->>API: POST /login
API->>DB: Validera inloggningsuppgifter
DB-->>API: Användarpost
API-->>App: Åtkomsttoken
App-->>User: Visa instrumentpanel
```
Ger följande diagram:
Vanliga sekvenspilar
-> solid linje utan pil
--> pricklinje utan pil
->> solid linje med pil
-->> pricklinje med pil
-x solid linje med kors
--x pricklinje med kors
Aktiveringsstänger
Aktiveringsstänger gör det tydligare när en aktör utför arbete.
denna kod:
```mermaid
sequenceDiagram
participant Client
participant Server
Client->>Server: Begär data
activate Server
Server-->>Client: Svar
deactivate Server
```
Ger följande diagram:
Alternativer och villkor
denna kod:
```mermaid
sequenceDiagram
participant User
participant API
participant Payment
User->>API: Skicka beställning
alt Betalningen lyckas
API->>Payment: Belasta kort
Payment-->>API: Godkänd
API-->>User: Beställning bekräftad
else Betalningen misslyckas
Payment-->>API: Avvisad
API-->>User: Visa fel
end
```
Ger följande diagram:
Sekvensdiagram är utmärkta för API-artiklar. De visar inte bara vilka komponenter som finns, utan hur de kommunicerar med varandra.
Klassdiagram-syntax
Klassdiagram är användbara för domänmodeller och objektrelationer.
denna kod:
```mermaid
classDiagram
class User {
+string id
+string email
+login()
+logout()
}
class Order {
+string id
+float total
+submit()
}
User "1" --> "*" Order
```
Ger följande diagram:
Klassrelationer
<|-- arv
*-- komposition
o-- aggregation
--> association
-- länk
..> beroende
..|> realisering
Exempel:
denna kod:
```mermaid
classDiagram
Animal <|-- Dog
Animal <|-- Cat
User "1" --> "*" Order
Order *-- OrderItem
```
Ger följande diagram:
Klassdiagram kan snabbt bli kladdiga. I ett blogginlägg, föredra en liten domänsnitt framför en fullständig applikationsmodell.
Statmaskin-syntax
Statmaskiner förklarar hur något förändras över tid.
denna kod:
```mermaid
stateDiagram-v2
[*] --> Draft
Draft --> Review: skicka
Review --> Published: godkänn
Review --> Draft: begär ändringar
Published --> Archived: arkivera
Archived --> [*]
```
Ger följande diagram:
Använd statmaskiner för:
- Beställningslivscykler
- Implementeringstillstånd
- Autentiseringsflöden
- Status för bakgrundsjobs
- Arbetsflöden för innehållspublikering
Statmaskiner är underskattade. De förklarar ofta affärslogik bättre än en lång stycke.
Entitetsrelationsdiagram-syntax
Entitetsrelationsdiagram är användbara för databasmodeller.
denna kod:
```mermaid
erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ ORDER_ITEM : contains
PRODUCT ||--o{ ORDER_ITEM : appears_in
USER {
string id
string email
}
ORDER {
string id
datetime created_at
}
PRODUCT {
string id
string name
}
```
Ger följande diagram:
ER-relationssymboler
|| exakt en
o| noll eller en
}| en eller flera
}o noll eller flera
ER-diagram är bäst när de förklarar relationer, inte varje kolumn. Håll implementeringsdetaljer i migrationer eller schemadokument.
Gantt-diagram-syntax
Gantt-diagram är användbara för projektens tidslinjer.
denna kod:
```mermaid
gantt
title Plan för dokumentationsmigration
dateFormat YYYY-MM-DD
section Planering
Granska nuvarande dokumentation :a1, 2026-06-01, 5d
Definiera struktur :a2, after a1, 3d
section Skrivning
Skriva om guider :b1, after a2, 10d
Granska och publicera :b2, after b1, 4d
```
Ger följande diagram:
Gantt-diagram är hjälpsamma i interna planeringsinlägg, men de kan åldras snabbt. Använd dem när tidslinjen i sig är poängen.
Tidslinjens syntax
Tidslinjer är bra för släpshistoriker, incidentrapporter och projektsummeringar.
denna kod:
```mermaid
timeline
title API-utveckling
2024 : REST API lanserad
2025 : Webhooks tillagd
2026 : Händelseström introducerad
```
Ger följande diagram:
Använd en tidslinje när ordning betyder mer än beroende. Om det du bryr dig om är händelseförloppet snarare än hur de kausalt hänger ihop, håller en tidslinje fokus där det hör hemma och är enkel att läsa på en blick.
Cirkeldiagram-syntax
Cirkeldiagram stöds, men var försiktig. De är lätta att läsa när det bara finns några få kategorier och värdena är tydligt olika.
denna kod:
```mermaid
pie title Byggtid per steg
"Installera beroenden" : 35
"Kör tester" : 45
"Bygg tillgångar" : 20
```
Ger följande diagram:
Åsikt: om värdena är nära varandra eller om det finns fler än fem kategorier, använd en tabell istället. En välformaterad tabell kommunicerar exakta siffror mer ärligt än ett cirkeldiagram där skivorna ser nästan identiska ut.
Git-graf-syntax
Git-grafer kan förklara grenstrategier och släppflöden.
denna kod:
```mermaid
gitGraph
commit
branch feature
checkout feature
commit
commit
checkout main
merge feature
commit
```
Ger följande diagram:
Detta är användbart för artiklar om Git-arbetsflöden, trunk-baserad utveckling, släppgrenar och hotfixar. Om du behöver en snabb referens för de underliggande grenkommandona, täcker GIT-fuskbladet de vanligaste tillsammans med merge- och rebase-arbetsflöden.
Mermaid Fuskblad
Diagramtyper
flowchart TD
sequenceDiagram
classDiagram
stateDiagram-v2
erDiagram
gantt
timeline
pie
gitGraph
mindmap
journey
Grundläggande flödesdiagram
flowchart TD
A[Text] --> B[Text]
A -->|Etikett| B
A -.-> B
A ==> B
A --- B
Flödesformer
A[Rektangel]
A(Rundad)
A{Beslut}
A((Cirkel))
A[(Databas)]
A[[Subrutin]]
A>Flagga]
Grundläggande sekvensdiagram
sequenceDiagram
participant A
participant B
A->>B: Meddelande
B-->>A: Svar
activate B
deactivate B
Sekvensblock
alt villkor
else annat villkor
end
opt valfritt steg
end
loop var item
end
par parallell uppgift
and another task
end
Grundläggande klassdiagram
classDiagram
class User
class Order
User --> Order
User "1" --> "*" Order
Grundläggande statmaskiner
stateDiagram-v2
[*] --> Idle
Idle --> Running
Running --> Done
Done --> [*]
Grundläggande ER-diagram
erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ ORDER_ITEM : contains
Kommentarer
Mermaid stödjer kommentarer med %%.
denna kod:
```mermaid
flowchart TD
%% Detta är en kommentar
A --> B
```
Ger följande diagram:
Användning av Mermaid i Hugo
Hugo-innehåll skrivs vanligtvis i Markdown, så Mermaid passar naturligt in i en teknisk blogg baserad på Hugo. Den exakta installationen beror på ditt tema och Markdown-renderingskonfiguration.
Det vanliga författarmönstret är fortfarande detsamma:
```mermaid
flowchart LR
Markdown --> Hugo
Hugo --> HTML
HTML --> Browser
```
Om ditt Hugo-tema redan stöder Mermaid, kan detta renderas utan extra arbete. Om det inte gör det behöver du vanligtvis en renderhook, shortcode, partial eller temakonfiguration som laddar Mermaid på sidor som innehåller Mermaid-diagram.
En praktisk Hugo-installation bör sikta på dessa regler:
- Håll Mermaid-källan inne i vanliga Markdown-artiklar.
- Ladda Mermaid bara på sidor som behöver den.
- Undvik global JavaScript om de flesta sidor inte använder diagram.
- Testa diagram under lokal förhandsgranskning.
- Håll diagramkällan läsbar i Git.
För en teknisk blogg är inhägnade kodblock vanligtvis bättre än anpassade shortcodes eftersom de är mer portabla. Om du senare flyttar innehåll till GitHub, en annan statisk sitegenerator eller en dokumentationsplattform, är standardinhägnade Mermaid-block lättare att återanvända.
Mermaid Bästa Praxer
Håll diagram små
Ett diagram bör förtydliga artikeln, inte ersätta den. Om läsarna behöver zooma är diagrammet förmodligen för stort.
Bra diagram har vanligtvis:
- En idé
- Tydlig riktning
- Korta etiketter
- Få korsande linjer
- Konsekvent namngivning
Föredrag flera små diagram
Använd flera fokuserade diagram istället för ett enormt systemdiagram:
- Begäranflöde
- Implementeringstopologi
- Datamodell
- Tillståndslivscykel
- Felväg
Detta är bättre för läsarna och bättre för mobila skärmar.
Använd stabila namn
Använd namn som matchar din kod, API eller dokumentation. Kalla inte samma sak API, Backend och Server i olika diagram om det inte är helt olika begrepp.
Märk viktiga pilar
Omärkta pilar är bra för enkla flödesdiagram. I systemdiagram betyder etiketter ofta något.
denna kod:
```mermaid
flowchart LR
Web -->|HTTPS-begäran| API
API -->|SQL-fråga| DB
API -->|publicera händelse| Queue
```
Ger följande diagram:
Undvik smart syntax
Mermaid kan göra många saker. Det betyder inte att varje artikel behöver dem. Föredra syntax som en framtida underhållsansvarig kan förstå snabbt.
Citera etiketter när det behövs
Om en etikett innehåller tecken som förvirrar Mermaid, vära den i citattecken.
denna kod:
```mermaid
flowchart TD
A["Användaren klickar på /checkout"] --> B["POST /api/orders"]
```
Ger följande diagram:
Detta är en liten vana som förhindrar irriterande renderingsfel.
Tänk på mörkt läge
Många Hugo-sidor stöder mörkt läge. Se till att ditt Mermaid-tema eller sidans CSS håller diagrammen läsbara i både ljus och mörk utseende.
Vanliga Mermaid-fel
Fel 1: För många detaljer
Dåliga Mermaid-diagram försöker ofta visa varje enskilt fall. Det gör dem tekniskt kompletta men praktiskt oläsliga. Fixet är nästan alltid detsamma: dela upp diagrammet i två eller tre mindre, var och en täcker ett problem, så att läsarna kan följa logiken utan att behöva spåra dussintals korsande pilar.
Fel 2: Långa etiketter
Långa etiketter skapar breda rutor och fula layouter.
Istället för denna kod:
```mermaid
flowchart TD
A[Användaren skickar registreringsformuläret med sin e-postadress och lösenord]
```
Ger följande diagram:
Föredra denna kod:
```mermaid
flowchart TD
A[Skicka registreringsformulär]
```
Ger följande diagram:
Förklara detaljer i stycket under diagrammet.
Fel 3: Oklar riktning
Välj en riktning och håll dig till den. De flesta procesdiagram bör använda TD. De flesta arkitekturdiagram är lättare att läsa med LR.
Fel 4: Att behandla Mermaid som ett designtverktyg
Mermaid är inte Figma. Det är inte tänkt för pixelperfekta diagram, och att försöka tvinga den i den rollen kommer bara att leda till frustration. Dess styrka är underhållbarhet, inte visuell perfektion — och den avvägningen är avsiktlig.
Mermaid SEO-tips för tekniska bloggar
Mermaid-diagram kan göra tekniska artiklar mer användbara, men sökmotorer behöver fortfarande text. Räkna inte enbart på diagram.
För SEO-vänliga Mermaid-artiklar:
- Använd beskrivande H2- och H3-rubriker.
- Förklara varje diagram i närliggande text.
- Inkludera de viktiga nyckelorden i vanlig prosa.
- Håll kodexemplen kopierbara.
- Lägg till en alternativ förklaring under komplexa diagram.
- Använd koncisa titel- och beskrivningsfält i frontmatter.
- Undvik att gömma all betydelse i den renderade SVG-filen.
Ett Mermaid-diagram bör stödja artikeln. Det bör inte vara den enda platsen där viktig information finns.
Kopiera-klistra Mermaid-exempel
API-begäranflöde
denna kod:
```mermaid
sequenceDiagram
participant Client
participant API
participant Auth
participant DB
Client->>API: GET /account
API->>Auth: Validera token
Auth-->>API: Token giltig
API->>DB: Ladda konto
DB-->>API: Kontodata
API-->>Client: 200 OK
```
Ger följande diagram:
CI-pipeline
denna kod:
```mermaid
flowchart TD
A[Push commit] --> B[Installera beroenden]
B --> C[Kör lint]
C --> D[Kör tester]
D --> E[Bygg webbplats]
E --> F[Implementera]
```
Ger följande diagram:
Detta mönster kartläggs naturligt mot en verklig CI-konfiguration. För steg-för-steg-syntaxen för GitHub Actions-arbetsflöden, är GitHub Actions-fuskbladet en handig följeslagare när du vill omvandla diagrammet ovan till en fungerande pipeline.
Publiceringsarbetsflöde
denna kod:
```mermaid
stateDiagram-v2
[*] --> Draft
Draft --> Editing
Editing --> Review
Review --> Published
Review --> Editing
Published --> [*]
```
Ger följande diagram:
Enkel datamodell
denna kod:
```mermaid
erDiagram
AUTHOR ||--o{ POST : writes
POST ||--o{ COMMENT : receives
AUTHOR {
string id
string name
}
POST {
string id
string title
datetime published_at
}
COMMENT {
string id
string body
}
```
Ger följande diagram:
När man inte ska använda Mermaid
Använd inte Mermaid när:
- Diagrammet behöver exakt visuell layout.
- Designen måste matcha ett varumärkessystem exakt.
- Den visuella bilden mestadels är dekorativ.
- Diagrammet har för många noder att läsa.
- En skärmdump skulle förklara poängen bättre.
- Innehållet ändras sällan och behöver mer polish än underhållbarhet.
Mermaid är utmärkt för levande teknisk dokumentation. Den är mindre bra för presentation-klass konstverk. För diagram av dokumentkvalitet i tryck- eller PDF-sammanhang erbjuder LaTeX paket som TikZ och pgfplots som ger dig mycket större layoutkontroll — LaTeX-fuskbladet täcker diagraminklusion tillsammans med resten av LaTeX-verktygslådan.
Avslutande tankar
Mermaid är ett av de bästa verktygen för teknisk bloggskrivning eftersom det respekterar hur utvecklare redan arbetar: textfiler, Markdown, Git, kodgranskning och upprepbara builds. För allt runt diagrammen — rubriker, listor, tabeller, kodblock — är Markdown-fuskbladet den snabba referenskompanjonen att hålla tillsammans med denna guide.
De bästa Mermaid-diagrammen är inte de mest komplexa. De är diagrammen som gör ett koncept uppenbart och förblir lätta att redigera sex månader senare.
Använd Mermaid för de diagram som bör leva med din dokumentation. Håll dem små, håll dem läsbara och behandla dem som en del av källkoden till din artikel.
