pal-e-docs

Mermaid Authoring Convention

mermaid-authoring Convention

active convention
Project

Mermaid Authoring Convention

How to write mermaid diagrams in pal-e-docs notes. Diagrams serve two audiences simultaneously: AI agents read raw mermaid syntax natively, humans see rendered diagrams in the /browse/ frontend.

Syntax

Use <pre class="mermaid"> blocks in note html_content:
The mermaid class triggers auto-initialization by mermaid.js in the browse frontend. No build step required.

Diagram Types

  • classDiagram — domain models, entity relationships. Standard: Domain Model in project pages.
  • flowchart LR — pipelines, left-to-right data flows. Standard: Data Flow in project pages.
  • graph TD / flowchart TD — component relationships, deployment topology. Standard: Deployment in project pages.
  • sequenceDiagram — workflows, request flows, lifecycle stages. Used in SOPs and plan phases as needed.

Guidelines

  • Keep diagrams 5-15 nodes. Split large diagrams into multiple focused ones.
  • Always pair diagrams with prose description. The diagram shows structure; prose explains why.
  • Use subgraph to group related components.
  • Label edges when the relationship isn't obvious from context.
  • Architecture sections in project pages and architecture notes SHOULD include mermaid diagrams.

Rendering

  • Browse frontend: mermaid.js v11 (CDN) auto-renders pre.mermaid blocks with neutral theme.
  • AI agents: Read raw html_content via MCP. The <pre class="mermaid"> syntax is readable as plain text.
  • CSS: pre.mermaid has no background and is centered for clean rendering.

Tagging

Notes that contain mermaid diagrams should include the mermaid tag for discoverability.