Connections use arrows: --> for a solid arrow, --- for a line without an arrow, -.-> for a dotted arrow, and ==> for a thick arrow.

A slightly more realistic example:

graph TD
 A[User visits login page] --> B{Has account?}
 B -- Yes --> C[Enter credentials]
 B -- No --> D[Sign up]
 C --> E{Valid?}
 E -- Yes --> F[Dashboard]
 E -- No --> G[Show error]
 G --> C

For more complex flowchart patterns and advanced layout techniques, check out our diagram coding tutorials that walk through progressively harder examples.

Sequence diagrams

Sequence diagrams show interactions between actors or systems over time. They're especially useful for documenting APIs, authentication flows, or any back-and-forth communication.

sequenceDiagram
 participant User
 participant Server
 participant Database
 User->>Server: Login request
 Server->>Database: Query user
 Database-->>Server: User data
 Server-->>User: Login success

The arrows matter here: ->> is a solid arrow, -->> is a dashed arrow (typically used for responses). Participants are declared at the top, and each line represents a message between them.

If you're working specifically on interaction diagrams, we have a separate resource covering sequence diagram markup language examples with detailed annotations.

Class diagrams

Mermaid also supports UML class diagrams, which are helpful for object-oriented design documentation:

classDiagram
 class Animal {
 +String name
 +int age
 +makeSound()
 }
 class Dog {
 +fetch()
 }
 class Cat {
 +purr()
 }
 Animal <|-- Dog
 Animal <|-- Cat

Symbols before attributes and methods indicate visibility: + for public, - for private, # for protected. Relationships like inheritance use <|-- and composition uses --.

For readers comparing different tools, our guide on PlantUML class diagram writing techniques covers how a similar tool handles class diagrams, which is useful for choosing the right syntax for your project.

Where can you actually use Mermaid diagrams?

Mermaid isn't just a novelty it works in places many people already spend their time:

• GitHub. Paste Mermaid code into any .md file and GitHub renders it automatically.
• Obsidian. Many developers use it for personal knowledge management and architecture notes.
• Confluence and Notion. Both support Mermaid through plugins or native blocks.
• Hugo, Docusaurus, MkDocs. Static site generators frequently support Mermaid for technical documentation.
• Slack. With certain apps, you can render Mermaid snippets in channels.

What mistakes do beginners commonly make?

After helping people learn Mermaid for a while, certain patterns keep showing up:

• Forgetting the diagram type declaration. Every diagram must start with a keyword like graph TD, sequenceDiagram, or classDiagram. Without it, nothing renders.
• Inconsistent arrow syntax. Mixing up --> and ->> across diagram types. Each diagram type has its own conventions double-check which arrows apply to which context.
• Using special characters in node labels without quotes. Characters like (, ), {, and } have meaning in Mermaid syntax. Wrap labels with problematic characters in quotes: A["Start (phase 1)"].
• Overcrowded diagrams. Just because you can put 30 nodes in one chart doesn't mean you should. Break complex flows into smaller, linked diagrams.
• Indentation issues. Mermaid isn't as strict about whitespace as Python, but inconsistent indentation in nested structures can cause unexpected rendering behavior.

What tips help you get better at Mermaid faster?

1. Use the live editor constantly. The instant feedback loop at mermaid.live is the fastest way to learn. Type something, see the result, adjust.
2. Start with existing examples. The official Mermaid documentation has examples for every diagram type. Copy them, modify them, break them, fix them.
3. Keep diagrams single-purpose. One diagram should answer one question. "How does the login flow work?" not "How does the entire system work?"
4. Use comments. You can add %% this is a comment inside your Mermaid code. Use them to explain non-obvious sections for future readers.
5. Name your nodes explicitly. Instead of relying on Mermaid's auto-generated IDs, give meaningful IDs like loginPage and authCheck. Your code stays readable months later.
6. Learn one diagram type at a time. Don't try to memorize flowchart, sequence, class, state, and Gantt syntax all at once. Get comfortable with flowcharts first the patterns carry over.

What should you do next?

Once you've built a few basic diagrams, push yourself with these steps:

• Document a real process at work using a Mermaid flowchart and share it with your team.
• Try embedding a diagram into a GitHub README file on a real project.
• Explore themes and styling Mermaid supports custom colors and themes through configuration blocks.
• Read about subgraphs, which let you group related nodes inside a flowchart for better organization.
• Compare Mermaid with PlantUML to understand which tool fits your workflow better.

Quick-start checklist for your first week with Mermaid

• Day 1: Open the Mermaid Live Editor and create a two-node flowchart.
• Day 2: Add decision nodes (diamonds) and multiple paths to a flowchart.
• Day 3: Build a sequence diagram showing a simple request-response interaction.
• Day 4: Create a class diagram with at least two classes and one relationship.
• Day 5: Embed a Mermaid diagram into a Markdown file on GitHub or your preferred editor.
• Day 6: Document a real workflow from your job or project something that's hard to explain in words.
• Day 7: Review your diagrams, refactor for clarity, and share one with someone else.

Mermaid rewards consistent small practice. You don't need to master the full syntax just start with one diagram type, build real diagrams for real needs, and expand from there.