1.3 Mermaid Syntax Basics

1. Explain how code blocks work: ```mermaid.

2. Describe graph TD (top-down) vs. graph LR (left-right).

3. Tips for syntax correctness and debugging.

---

1. Explain How Code Blocks Work: ```mermaid

The simplest and most common way to write a Mermaid diagram is by using a code block in your Markdown file. If you’ve ever written a code snippet in Markdown, you’re already familiar with this basic idea — Mermaid just builds on it with a special syntax highlight.

---

✅ What is a Code Block?

In Markdown, a code block is a way to tell your editor or documentation tool, “Render this text exactly as I wrote it — don’t format it like regular paragraphs.”

A standard code block is created using three backticks (```) before and after your code. You can also add a language tag right after the opening backticks to tell your tool what type of code it is — for example:

```python
print("Hello, world!")
```

This tells the Markdown renderer to highlight the syntax for Python.

---

✅ How Mermaid Uses Code Blocks

Mermaid diagrams work the same way. To create a Mermaid diagram, you start a code block with three backticks and the word mermaid right after:

```mermaid
graph TD
  A --> B
  B --> C
```

• ```mermaid tells your Markdown tool or integration to interpret the content as Mermaid syntax instead of generic code.

• Inside the block, you write your Mermaid markup — the nodes, arrows, and relationships that describe your diagram.

• When your Markdown is rendered in a tool that supports Mermaid (like GitBook, GitHub, GitLab, or Obsidian), it automatically converts the text to a visual diagram.

---

✅ How It Looks in Practice

For example, this code block:

```mermaid
graph LR
  Start --> Process --> End
```

will render as a simple left-to-right flowchart that shows “Start” leading to “Process,” which then leads to “End.”

---

✅ Best Practices

• Always check that your opening and closing backticks match — it’s easy to forget the closing ```.

• Keep your Mermaid code indented properly to avoid confusion with other Markdown elements.

• If your diagram doesn’t render, double-check that you’re using the correct keyword: mermaid (not memaid, merm, or other typos).

---

In short:

The ```mermaid code block is the foundation of writing Mermaid diagrams — simple, clear, and easy to drop right into any Markdown file.

---

2. Describe graph TD (Top-Down) vs. graph LR (Left-Right)

When creating diagrams with Mermaid, one of the first things you write is the direction your diagram should flow. Mermaid uses a simple keyword to define this: graph followed by a direction code.

This small piece of syntax controls whether your flowchart, process diagram, or architecture map draws from top to bottom or from left to right.

---

✅ graph TD: Top-Down

• TD stands for Top-Down.

• This means nodes flow vertically, starting at the top and moving downward.

• It’s a good default for process flows, step-by-step instructions, or hierarchical structures — like decision trees or organizational charts.

Example:

```mermaid
graph TD
  Start --> Step1 --> Step2 --> End
```

How it looks:

• “Start” appears at the top.

• Arrows flow downward through each step until they reach “End” at the bottom.

---

✅ graph LR: Left-Right

• LR stands for Left to Right.

• This draws your diagram horizontally, starting on the left and moving to the right.

• It’s great for simple flows, timelines, or processes where it’s clearer to read side to side.

Example:

```mermaid
graph LR
  Start --> Step1 --> Step2 --> End
```

How it looks:

• “Start” appears on the left.

• Arrows flow rightward through each step until they reach “End” on the far right.

---

✅ Other Layouts

While TD (Top-Down) and LR (Left-Right) are the most common, Mermaid also supports:

• RL — Right to Left

• BT — Bottom to Top

These give you extra flexibility for special cases, like when you need to mirror a flow or fit a diagram into a specific page layout.

---

✅ How to Choose

The choice is simple:

• Use TD when your process or hierarchy makes more sense vertically.

• Use LR when a flow or timeline works better horizontally.

---

In short:

graph TD and graph LR are easy but powerful tools that shape how your diagram is laid out — giving you full control with just two letters.

---

3. Tips for Syntax Correctness and Debugging

Writing Mermaid diagrams is straightforward — but like any code, small syntax mistakes can cause your diagram to break or not render at all. Luckily, Mermaid is very forgiving once you know a few simple checks. Here are some practical tips to help you keep your diagrams error-free and easy to fix when something goes wrong:

---

✅ Use the Right Fenced Code Block

Always start and end your diagram with a proper Mermaid code block:

```mermaid
graph TD
  A --> B
```

• Make sure you have three backticks ``` at the beginning and end.

• Always spell mermaid correctly — typos like memaid or merm are common causes of blank diagrams!

---

✅ Check Node Names

Mermaid nodes can contain letters, numbers, and some special characters — but they should be clear and unique:

A --> B

• Avoid using spaces in node IDs — use - or _ if needed: Step_1 or Step-1.

• If you want spaces in the label, wrap it in quotes or brackets:

  A["Start Node"] --> B["End Node"]

---

✅ Watch Your Arrows

Make sure your arrows have the correct syntax:

• Use --> for a normal arrow.

• Add labels with -->|Label|:

  A -->|Yes| B

Small typos like -> (missing -) or wrong symbols will break the connection.

---

✅ Preview Frequently

Use tools like:

• Mermaid Live Editor (mermaid.live) — paste your code and see instant results.

• Preview mode in VS Code, Obsidian, or GitBook to check your diagram in context.

If it doesn’t render:

• Start with a small piece of the diagram.

• Add one node or arrow at a time until it breaks — then you know exactly where the problem is.

---

✅ Indent Consistently

While Mermaid doesn’t require strict indentation, clean spacing makes your diagram easier to read and debug. Especially for nested elements (like subgraphs or loops), clear indentation helps you spot structure mistakes.

---

✅ Read Error Messages

Some editors and live preview tools show helpful error hints if your syntax is invalid. Pay attention to the console or side panel — they often point you right to the line with the problem.

---

✅ Keep Examples Handy

When you’re unsure, look up examples in:

• The official Mermaid documentation

• The Mermaid Live Editor templates

• Diagrams you’ve written before

Copying a working example and adjusting it line by line is one of the fastest ways to learn and fix issues.

---

In short:

✅ Double-check your code blocks, nodes, arrows, and spacing. ✅ Use a live preview to test often. ✅ Build your diagram step by step — and fix small mistakes as you go.

With these simple habits, you’ll catch most syntax issues quickly and keep your Mermaid diagrams clear, reliable, and easy to update.

---