Draw Diagrams with Mermaid

Purpose

This skill allows the agent to generate diagrams (PNG, SVG, PDF) from Mermaid text syntax. It follows a robust workflow involving markdown files and verification.

1. Safety & Verification

Before executing any commands, the agent must:

1. Check Tool: Verify mmdc is installed by running mmdc --version.
2. Verify Syntax: All node labels MUST be double-quoted (e.g., A["Start"]).
3. Reference Examples: Consult .cursor/skills/draw-diagrams-with-mermaid/references/mermaid-syntax.md for compliant examples.

2. Common Workflows

Workflow: Generate Diagram from Markdown (Primary)

The standard way to generate a diagram is to first create a markdown file containing the Mermaid block and then render it.

1. Create Markdown File: Write the Mermaid code into a .md file.

   • Crucial Rule: Use double quotes for all node labels.
   • Crucial Rule: The file MUST ONLY contain the Mermaid code block (no titles, extra text, etc.).

2. Render Diagram: Run the helper script to generate the image.

   .cursor/skills/draw-diagrams-with-mermaid/scripts/draw-from-md.sh input.md [output.png]
   

   • Default output format is PNG.
   • You can specify other extensions (e.g., output.svg, output.pdf) to change the format.

3. Verify & Fix:

   • If the command fails (non-zero exit code), read the error message from the terminal.
   • Analyze the syntax error, fix the Mermaid code in the markdown file, and retry.
   • Repeat until the diagram is successfully generated.

3. Implementation Rules

1. Double Quoting: Every label in the diagram must be wrapped in double quotes.
   • Good: A["Start"], B{"Decision"}
   • Bad: A[Start], B{Decision}
2. No Configuration Files: Do not use the assets/default-config.json or any other external configuration file unless explicitly asked. Rely on standard mmdc defaults.
3. Persistence: Keep the markdown file as a source of truth for the diagram.
4. Code Block Only: The input markdown file must contain nothing but the Mermaid code block. Do not include headers, descriptions, or other Markdown elements.

4. Error Handling

• mmdc failure: Usually indicates a syntax error. Common issues:
  • Missing double quotes on labels.
  • Incorrect arrow syntax (e.g., using -> instead of --> in flowcharts).
  • Unclosed braces or brackets.
• Output file not found: The draw-from-md.sh script handles renaming logic if mmdc adds suffixes like -1.png. If it still fails, check permissions.

5. Examples

Example: Valid Flowchart (PNG)

1. Write logic.md (The file includes only this code block):

graph TD
    A["Input"] --> B{"Valid?"}
    B -- "Yes" --> C["Process"]
    B -- "No" --> D["Reject"]

1. Run Command:

   .cursor/skills/draw-diagrams-with-mermaid/scripts/draw-from-md.sh logic.md
   

Example: Valid Sequence Diagram (SVG)

1. Write auth.md (The file includes only this code block):

sequenceDiagram
    User->>Server: "Login Request"
    Server-->>User: "Auth Token"

1. Run Command:

.cursor/skills/draw-diagrams-with-mermaid/scripts/draw-from-md.sh auth.md auth-flow.svg