Mermaid

Mermaid Diagrams

Skill for generating Mermaid diagrams embedded in markdown fences. Mermaid is used for inline documentation — flowcharts, sequences, state machines, ER diagrams, Gantt charts. For architecture diagrams with Azure service icons, use the python-diagrams skill instead.

When to Use Mermaid

• Inline diagrams inside markdown (.md, .mdx)
• Flowcharts for operational runbooks and process docs
• Sequence diagrams for auth flows and API interactions
• Gantt charts for project plans and maintenance schedules
• State diagrams for lifecycle documentation
• ER diagrams for data model overviews
• Azure resource relationship diagrams from live queries (via azure-resources Mode B)

Rules

DO: fenced code blocks with mermaid language tag · include theme directives for dark mode · graph TB (vertical) or graph LR (horizontal) · subgraphs for grouping · descriptive connection labels · validate syntax before committing.

DON'T: use Mermaid for WAF/cost charts (use python-diagrams) · use Mermaid for rendered architecture diagrams (use python-diagrams) · omit theme directives · embed Azure service icons.

Steps

1. Pick the diagram type — see references/syntax-cheatsheet.md
2. Author inside a triple-backtick mermaid fence in your markdown
3. Add theming and node styles — see references/styling.md
4. Validate — render in VS Code preview or Starlight build
5. Commit — the rendered Mermaid stays inline; no separate artifact

Reference Index

Scope Exclusions

Does NOT: generate rendered architecture diagrams · produce Python charts · generate Bicep/Terraform · create ADRs · deploy resources · embed Azure service icons (use python-diagrams).