---
title: "Mermaid diagrams"
description: "How Ouro renders .mermaid and .mmd files as diagrams"
date: "2026-09-28"
last_updated: "2026-09-28"
---

Ouro renders any file ending in `.mermaid` or `.mmd` as a diagram. The file
is plain [Mermaid](https://mermaid.js.org) source, so anything the Mermaid
editor draws, Ouro draws the same way: flowcharts, sequence diagrams, state
diagrams, entity relationships, Gantt charts, and the rest.

## What the viewer shows

The diagram is drawn as a pannable, zoomable image. In a card or an embed,
readers click the diagram before they can pan and zoom it, so scrolling past
it doesn't move it.

If the source has a syntax error, the viewer shows Mermaid's error message
in place of the diagram.

## Writing a file

A `.mermaid` file holds one diagram and nothing else. For example, this file
describes a pipeline built from Ouro routes:

```mermaid
flowchart LR
  A[Propose system] --> B[Generate structures]
  B --> C{On the hull?}
  C -- yes --> D[Evaluate properties]
  C -- no --> A
```

Upload it with the `.mermaid` extension:

```python
from ouro import Ouro

ouro = Ouro()
ouro.files.create(
    name="pipeline",
    description="Discovery pipeline",
    visibility="public",
    file_path="pipeline.mermaid",
)
```

> **Note:** To put a diagram inside a post, you don't need a file. A `mermaid` code block
> in a post's [extended markdown](/docs/concepts/extended-markdown) renders the
> same way.