Files

T

can1357 57958ab4b7 docs: clarify RenderMermaid usage

RenderMermaid is disabled by default and emits terminal text rather
than SVG/PNG; complex sequence diagrams with alt/else blocks become
hard to read at default widths. Add docs/render-mermaid.md covering
enablement (renderMermaid.enabled), config knobs (useAscii, paddingX,
paddingY, boxBorderPadding), output expectations, and limitations.
Link the new guide from the coding-agent README.

Fixes #961

2026-05-09 03:11:18 +02:00

2.1 KiB

Raw Blame History

RenderMermaid

RenderMermaid is an optional built-in tool that renders Mermaid source to terminal-friendly text.

Enable it

Disabled by default. Turn it on in /settings under Tools → Render Mermaid, or in ~/.omp/agent/config.yml:

renderMermaid:
  enabled: true

What it does

Tool name: render_mermaid
Input: Mermaid source in the required mermaid field
Output: rendered ASCII/Unicode text, not SVG or PNG
Storage: when artifact storage is available, the full render is also saved as an artifact://...

There are no model-specific or environment-variable prerequisites. Once enabled, any model that can call built-in tools can use it.

Parameters

{
  "mermaid": "graph TD\n  A[Start] --> B[Stop]",
  "config": {
    "useAscii": false,
    "paddingX": 2,
    "paddingY": 2,
    "boxBorderPadding": 0
  }
}

Available config fields:

useAscii — true for plain ASCII, false for Unicode box-drawing characters (default and usually more readable)
paddingX — horizontal spacing between nodes
paddingY — vertical spacing between nodes
boxBorderPadding — inner padding inside node boxes

Current limitations

RenderMermaid uses the beautiful-mermaid ASCII renderer. It works best for flowcharts and small diagrams.

Complex sequence diagrams, especially with alt / else blocks, can become very wide in a terminal. That is current renderer behavior, not a provider or model configuration problem.

If a sequence diagram is hard to read:

Keep Unicode output (useAscii: false)
Reduce spacing with a tighter config such as paddingX: 2, paddingY: 2, boxBorderPadding: 0
Prefer smaller sub-diagrams over one large sequence diagram
Open the saved artifact if the inline preview is truncated in the TUI

Example

Input:

graph TD
  A[Start] --> B{Decision}
  B -->|Yes| C[Action]
  B -->|No| D[End]

Typical result:

┌─────┐
│Start│
└─────┘
   │
   ▼
┌────────┐
│Decision│
└────────┘

2.1 KiB Raw Blame History