# Mermaid Diagrams

Embeds Mermaid diagrams in wiki pages for flows, sequences, states, and data models.

- Repository: https://github.com/langchain-ai/openwiki (17657 stars)
- Category: Documents
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add langchain-ai/openwiki --skill mermaid-diagrams -g -a claude-code -y`
Codex: `npx skills add langchain-ai/openwiki --skill mermaid-diagrams -g -a codex -y`
Cursor: `npx skills add langchain-ai/openwiki --skill mermaid-diagrams -g -a cursor -y`
Gemini CLI: `npx skills add langchain-ai/openwiki --skill mermaid-diagrams -g -a gemini-cli -y`

## Description

Embed Mermaid diagrams in generated wiki pages. Use whenever documenting a runtime or request flow, a call sequence, a state machine or lifecycle, a data model or entity relationships, or non-trivial control flow, since these are clearer as a diagram than as prose. Also use when an update run touches a page that already contains a mermaid fence, or a page that contains a text fence a previous run degraded.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Mermaid Diagrams In Generated Wiki Pages

Diagrams are part of high-quality wiki generation, not decoration. Where a flow,
lifecycle, or data model is easier to grasp visually, embed a Mermaid diagram in
a fenced ```mermaid block on the most relevant page.

## Choosing a diagram type

- `sequenceDiagram` for runtime and request flows across components (auth flows, request lifecycles, agent tool loops).
- `stateDiagram-v2` for lifecycles and state machines (job states, connection states, run phases).
- `erDiagram` for the data model: entities and their relationships.
- `flowchart TD` for branching control flow and decision logic.

## Discipline

- Ground every diagram in inspected source. Do not invent participants, states, entities, or relationships the code does not support.
- Cover the high-value cases: add a diagram wherever a page documents a request or runtime flow, a call sequence, a lifecycle or state machine, or a data model. A repository wiki usually has several such diagrams, not one overall. Skip pages that are navigation, reference tables, or pure configuration.
- Still prefer a few strong diagrams over decorating every page: one accurate diagram on the page that needs it beats a diagram forced onto every page.
- Give each diagram a one-line caption directly below it stating what it shows.
- OpenWiki validates every mermaid fence after your run and converts fences that fail to parse into plain text fences. A degraded diagram is a quality failure; follow the syntax rules below so it does not happen.

## Syntax safety

These rules prevent the most common render breakages. When in doubt, rephrase the label.

The rest: https://github.com/langchain-ai/openwiki/blob/HEAD/skills/mermaid-diagrams/SKILL.md