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

# Mermaid diagrams

Turn a text description into a diagram that follows your site's theme. Edit the
connections alongside the explanation, then present the same result in Player.

```mermaid
flowchart LR
  Write --> Preview --> Revise
  Revise --> Write
```

---

## Install and draw a diagram

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

```sh
bun run pmx plugins add mermaid
```

This records the package and activates its ready-to-use Beautiful Mermaid renderer
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
  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” in the diagram and save to see
the result update. The diagram's larger-view control opens a dialog; Escape
returns to the page. Review it in Focus and Slides when Player is installed.

---

## Recover from invalid syntax

A renderer error leaves the original code fence visible and logs a rendering
warning identifying the Source. For example, change `flowchart LR` to an invalid
diagram declaration, save, and inspect the server warning. Restore the valid
fence above to recover; the rest of the page remains readable.

The renderer loads only for a Source with a Mermaid fence. Colors follow the
active PathMX theme. Static export includes the rendered result and viewer assets;
readers do not need to install a diagram renderer themselves.

---

## Supply a different renderer

`MermaidPlugin` from `@pathmx/mermaid` accepts a function with the contract
`(code: string) => string | Promise<string>`, returning SVG. The ready-to-use
`BeautifulMermaidPlugin` is exported from `@pathmx/mermaid/beautiful`.
Use a [configured repository Plugin](../extend/plugins.guide.md#organize-and-compose-plugins)
only when your application has a complete alternate renderer to supply. The
normal installation above needs no custom wrapper.

## Related

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