[@layout]: ../docs.layout.md

# Diagrams

Turn a text description into a diagram that follows your site's theme and fits the
reader's screen. Write Mermaid beside the explanation, then present the same result
in Player.

```mermaid
flowchart LR
  accTitle: Writing cycle
  Write --> Preview --> Revise
  Revise --> Write
```

---

## Install and draw a diagram

In an initialized [Quickstart project](../start/first-site.guide.md), install
`@pathmx/diagrams` with the project-local command:

```sh
bun run pmx plugins add diagrams
```

This records the package and activates it in the project manifest. Create
`paths/process.page.md`:

````md
# Improve a page

Write one useful idea, preview it, then revise what needs work.

```mermaid
flowchart LR
  accTitle: Writing cycle
  Write --> Preview --> Revise
  Revise --> Write
```
````

Run `bun run dev` and open `/process.page`. The three stages form a cycle, like
the opening diagram. Change “Preview” to “Try it” and save to see the diagram
update. Narrow the window: the diagram rearranges itself to fit the column,
turning vertical when it runs out of room, instead of shrinking its text.

When a diagram has to shrink to fit, its larger-view control opens it in a
dialog. Pinch or use Ctrl or ⌘ with the scroll wheel to zoom, drag to pan, and
use `+`, `-`, `0` and the arrow keys while the diagram has focus. Escape returns
to the page. Review it in Focus and Slides when Player is installed.

---

## Write Mermaid

A `` ```mermaid `` fence accepts the syntax of Mermaid 12.1 for every built-in
diagram type except ZenUML. Those types include flowcharts, sequence, class,
state, entity relationship, Gantt, pie, mindmap, timeline, user journey, Git
graph, quadrant, XY chart, Sankey, C4, architecture, block, kanban and treemap
diagrams. The [Pele examples](https://pele.run/examples) show each type, and
the [playground](https://pele.run/playground) previews a diagram as PathMX draws
it.

```mermaid
gantt
  title Project 2
  dateFormat YYYY-MM-DD
  section Build
  Prototype :p1, 2026-10-20, 5d
  Playtest  :after p1, 3d
```

PathMX lays diagrams out with its own engine, so positions and edge routes can
differ from other Mermaid renderers. Labels support line breaks, bold and italic
text, but not HTML.

A sequence message runs to the end of its line and needs no quotes. Mermaid ends
a message at a semicolon; write `#59;` for a literal one:

```mermaid
sequenceDiagram
  Author->>Site: publish the page#59; then review it
```

`accTitle` and `accDescr` give a diagram an accessible name and description.
`click` statements link a node to an `http`, `https`, `mailto` or `tel` URL.

---

## Match the theme

Diagram colors and fonts follow the active PathMX theme in light and dark mode.
To adjust diagrams alone, set Pele's [theme variables](https://pele.run/theming)
on `.pmx-diagram` in a [stylesheet](../site/styles.reference.md):

```css
.pmx-diagram {
  --pele-line: var(--pmx-color-fg);
  --pele-radius: 0;
}
```

Colors written in a diagram with `style` or `classDef` stay fixed when the theme
changes.

---

## Recover from invalid syntax

`bun run pmx lint` reports a diagram it cannot draw at the Source line and column
of the problem. The page keeps the original code fence visible and logs a
rendering warning; the rest of the page remains readable. Restore valid syntax to
see the diagram again.

The renderer loads only for a Source with a Mermaid fence, and the browser loads
only the diagram types a page uses. Static export includes each rendered diagram,
so readers without JavaScript still see it.

## Related

- [Markdown](./markdown.reference.md) · [Player](../learning/player.reference.md)
- [Reuse content](./reuse-content.guide.md)