Initial commit

2025-11-29 18:48:31 +08:00
commit 1041424521
9 changed files with 2841 additions and 0 deletions
--- a/skills/mermaid/flowchart-diagram-reference.md
+++ b/skills/mermaid/flowchart-diagram-reference.md
@@ -0,0 +1,878 @@
+# Flowchart Diagram Reference
+
+Comprehensive syntax reference for creating flowchart diagrams in Mermaid. Flowcharts consist of **nodes** (geometric shapes) and **edges** (connecting lines/arrows) that visualize processes, decision logic, algorithms, and workflows.
+
+## Basic Syntax
+
+All flowcharts start with the `flowchart` keyword followed by an optional direction:
+
+```mermaid
+flowchart TD
+    Start --> Stop
+```
+
+## Direction Control
+
+Control the orientation of your flowchart:
+
+| Direction | Description |
+|-----------|-------------|
+| `TB` or `TD` | Top to Bottom (default) |
+| `BT` | Bottom to Top |
+| `LR` | Left to Right |
+| `RL` | Right to Left |
+
+**Example:**
+```mermaid
+flowchart LR
+    A --> B
+```
+
+---
+
+## Node Shapes
+
+### Basic Node Types
+
+#### Default Node (Rectangle with Text)
+```mermaid
+flowchart TD
+    id
+    id1[This is the text in the box]
+```
+
+#### Round Edges (Rounded Rectangle)
+```mermaid
+flowchart TD
+    id1(This is the text in the box)
+```
+
+#### Stadium Shape (Pill Shape)
+```mermaid
+flowchart TD
+    id1([This is the text in the box])
+```
+
+#### Subroutine (Rectangle with Vertical Lines)
+```mermaid
+flowchart TD
+    id1[[This is the text in the box]]
+```
+
+#### Cylinder (Database)
+```mermaid
+flowchart TD
+    id1[(Database)]
+```
+
+#### Circle
+```mermaid
+flowchart TD
+    id1((This is the text in the circle))
+```
+
+#### Double Circle
+```mermaid
+flowchart TD
+    id1(((This is the text in the circle)))
+```
+
+#### Asymmetric Shape
+```mermaid
+flowchart TD
+    id1>This is the text in the box]
+```
+
+#### Diamond/Rhombus (Decision)
+```mermaid
+flowchart TD
+    id1{This is the text in the box}
+```
+
+#### Hexagon
+```mermaid
+flowchart TD
+    id1{{This is the text in the box}}
+```
+
+#### Parallelogram (Input/Output)
+```mermaid
+flowchart TD
+    id1[/This is the text in the box/]
+```
+
+#### Parallelogram Alt
+```mermaid
+flowchart TD
+    id1[\This is the text in the box\]
+```
+
+#### Trapezoid
+```mermaid
+flowchart TD
+    A[/Christmas\]
+```
+
+#### Trapezoid Alt
+```mermaid
+flowchart TD
+    B[\Go shopping/]
+```
+
+### Node Shape Quick Reference Table
+
+| Shape | Syntax | Common Use |
+|-------|--------|------------|
+| Rectangle | `id[Text]` | Process/Action |
+| Round edges | `id(Text)` | Start/End |
+| Stadium | `id([Text])` | Start/End (alternate) |
+| Subroutine | `id[[Text]]` | Predefined process |
+| Cylinder | `id[(Text)]` | Database |
+| Circle | `id((Text))` | Connection point |
+| Double circle | `id(((Text)))` | Special endpoint |
+| Diamond | `id{Text}` | Decision/Condition |
+| Hexagon | `id{{Text}}` | Preparation |
+| Parallelogram | `id[/Text/]` | Input/Output |
+| Trapezoid | `id[/Text\]` | Manual operation |
+
+---
+
+## Text Formatting
+
+### Unicode Support
+Use quotes for Unicode characters:
+```mermaid
+flowchart LR
+    id["This ❤ Unicode"]
+```
+
+### Markdown in Nodes
+Use backticks with double quotes for markdown formatting:
+```mermaid
+flowchart LR
+    markdown["`This **is** _Markdown_`"]
+    newLines["`Line1
+    Line2
+    Line3`"]
+```
+
+Supports:
+- **Bold**: `**text**`
+- *Italics*: `*text*`
+- Line breaks (automatic wrapping)
+
+---
+
+## Edges/Links
+
+### Basic Link Types
+
+#### Standard Arrow
+```mermaid
+flowchart LR
+    A-->B
+```
+
+#### Open Link (No Arrow)
+```mermaid
+flowchart LR
+    A --- B
+```
+
+#### Text on Link
+```mermaid
+flowchart LR
+    A-- This is the text! ---B
+    C---|This is the text|D
+```
+
+#### Arrow with Text
+```mermaid
+flowchart LR
+    A-->|text|B
+    C-- text -->D
+```
+
+#### Dotted Link
+```mermaid
+flowchart LR
+    A-.->B
+```
+
+#### Dotted Link with Text
+```mermaid
+flowchart LR
+    A-. text .-> B
+```
+
+#### Thick Link
+```mermaid
+flowchart LR
+    A ==> B
+```
+
+#### Thick Link with Text
+```mermaid
+flowchart LR
+    A == text ==> B
+```
+
+#### Invisible Link (for spacing)
+```mermaid
+flowchart LR
+    A ~~~ B
+```
+
+### Special Edge Types
+
+#### Circle Edge
+```mermaid
+flowchart LR
+    A --o B
+```
+
+#### Cross Edge
+```mermaid
+flowchart LR
+    A --x B
+```
+
+### Multi-directional Arrows
+
+```mermaid
+flowchart LR
+    A o--o B
+    B <--> C
+    C x--x D
+```
+
+### Edge Types Quick Reference
+
+| Type | Syntax | Description |
+|------|--------|-------------|
+| Standard arrow | `A-->B` | Directional flow |
+| Open link | `A---B` | Connection without direction |
+| Arrow with text | `A-->|text|B` | Labeled flow |
+| Dotted arrow | `A-.->B` | Optional/alternative path |
+| Thick arrow | `A==>B` | Emphasized flow |
+| Invisible link | `A~~~B` | Hidden connection (spacing) |
+| Circle edge | `A--oB` | Special connection |
+| Cross edge | `A--xB` | Terminated/blocked flow |
+| Bidirectional | `A<-->B` | Two-way flow |
+
+---
+
+## Link Length Control
+
+Control the visual length of connections by adding extra dashes or dots:
+
+| Length Type | 1 | 2 | 3 |
+|---|---|---|---|
+| Normal | `---` | `----` | `-----` |
+| With arrow | `-->` | `--->` | `---->` |
+| Thick | `===` | `====` | `=====` |
+| Thick arrow | `==>` | `===>` | `====>` |
+| Dotted | `-.-` | `-..-` | `-...-` |
+| Dotted arrow | `-.->` | `-..->` | `-...->` |
+
+**Example:**
+```mermaid
+flowchart TD
+    A --> B
+    A ---> C
+    A -----> D
+```
+
+---
+
+## Chaining Links
+
+### Sequential Chaining
+Connect multiple nodes in one line:
+```mermaid
+flowchart LR
+    A -- text --> B -- text2 --> C
+```
+
+### Parallel Connections with Ampersand
+Connect multiple nodes to multiple targets:
+```mermaid
+flowchart TD
+    a --> b & c --> d
+```
+
+Multiple sources to multiple targets:
+```mermaid
+flowchart TD
+    A & B --> C & D
+```
+
+---
+
+## Subgraphs
+
+Group related nodes together using subgraphs.
+
+### Basic Subgraph
+```mermaid
+flowchart TB
+    c1-->a2
+    subgraph one
+        a1-->a2
+    end
+    subgraph two
+        b1-->b2
+    end
+    subgraph three
+        c1-->c2
+    end
+```
+
+### Subgraph with Explicit ID
+```mermaid
+flowchart TB
+    subgraph ide1 [one]
+        a1-->a2
+    end
+```
+
+### Nested Subgraphs
+```mermaid
+flowchart TB
+    subgraph TOP
+        direction TB
+        subgraph B1
+            direction RL
+            i1 -->f1
+        end
+        subgraph B2
+            direction BT
+            i2 -->f2
+        end
+    end
+    A --> TOP --> B
+```
+
+### Direction in Subgraphs
+```mermaid
+flowchart LR
+    subgraph TOP
+        direction TB
+        subgraph B1
+            direction RL
+            i1 -->f1
+        end
+    end
+```
+
+**Note:** External node links can override subgraph direction settings.
+
+---
+
+## Styling
+
+### Link Styling
+
+Apply styles to specific links by their order (zero-indexed):
+
+```mermaid
+flowchart LR
+    A-->B
+    B-->C
+    C-->D
+    D-->E
+    linkStyle 0 stroke:#ff3,stroke-width:4px,color:red;
+    linkStyle 3 stroke:#00f,stroke-width:2px;
+```
+
+Style multiple links at once:
+```mermaid
+flowchart LR
+    A-->B
+    B-->C
+    C-->D
+    linkStyle 0,1,2 color:blue;
+```
+
+### Node Styling
+
+Apply inline styles to specific nodes:
+
+```mermaid
+flowchart LR
+    id1(Start)-->id2(Stop)
+    style id1 fill:#f9f,stroke:#333,stroke-width:4px
+    style id2 fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
+```
+
+**Available style properties:**
+- `fill`: Background color
+- `stroke`: Border color
+- `stroke-width`: Border width
+- `color`: Text color
+- `stroke-dasharray`: Dashed border pattern
+
+### Classes
+
+Define reusable style classes:
+
+```mermaid
+flowchart LR
+    A:::someclass --> B
+    classDef someclass fill:#f96
+```
+
+Apply class to multiple nodes:
+```mermaid
+flowchart LR
+    A-->B[AAA<span>BBB</span>]
+    B-->D
+    class A cssClass
+```
+
+**Class definition syntax:**
+```mermaid
+flowchart TD
+    A[Start] --> B[Process]
+    classDef green fill:#9f6,stroke:#333,stroke-width:2px;
+    classDef orange fill:#f96,stroke:#333,stroke-width:4px;
+    class A green
+    class B orange
+```
+
+### Default Class
+
+Apply styles to all nodes without specific styling:
+
+```mermaid
+flowchart TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[OK]
+    B -->|No| D[Not OK]
+    classDef default fill:#f9f,stroke:#333,stroke-width:2px;
+```
+
+### CSS Classes
+
+Reference predefined CSS classes from your HTML/stylesheet:
+
+```html
+<style>
+    .cssClass > rect {
+        fill:#FF0000;
+        stroke:#FFFF00;
+        stroke-width:4px;
+    }
+</style>
+```
+
+```mermaid
+flowchart LR
+    A-->B[AAA<span>BBB</span>]
+    B-->D
+    class A cssClass
+```
+
+---
+
+## Curve Styles
+
+Control the curve interpolation of edges at the diagram level:
+
+```mermaid
+---
+config:
+  flowchart:
+    curve: stepBefore
+---
+flowchart LR
+    A --> B --> C
+```
+
+**Available curve types:**
+- `basis`
+- `bumpX`
+- `bumpY`
+- `cardinal`
+- `catmullRom`
+- `linear` (default)
+- `monotoneX`
+- `monotoneY`
+- `natural`
+- `step`
+- `stepAfter`
+- `stepBefore`
+
+---
+
+## Advanced Features
+
+### Edge IDs and Animation
+
+Assign IDs to edges and apply animations:
+
+```mermaid
+flowchart LR
+    A e1@--> B
+    e1@{ animate: true }
+```
+
+**Animation speeds:**
+- `fast`
+- `slow`
+
+### Icons in Nodes
+
+Add FontAwesome icons to nodes:
+
+```mermaid
+flowchart TD
+    A@{ icon: "fa:user", form: "square", label: "User Icon", pos: "t", h: 60 }
+    B@{ icon: "fa:database", form: "circle", label: "Database", pos: "b" }
+```
+
+**Icon parameters:**
+- `icon`: Icon identifier (e.g., `"fa:user"`)
+- `form`: Shape - `square`, `circle`, `rounded`
+- `label`: Text label
+- `pos`: Position - `t` (top), `b` (bottom)
+- `h`: Height in pixels
+- `w`: Width in pixels
+
+### Images in Nodes
+
+Embed images in nodes:
+
+```mermaid
+flowchart LR
+    A@{ img: "https://example.com/image.png", label: "Label", w: 60, h: 60, constraint: "on" }
+```
+
+**Image parameters:**
+- `img`: Image URL
+- `label`: Text label
+- `w`: Width in pixels
+- `h`: Height in pixels
+- `constraint`: Layout constraint (`"on"` or `"off"`)
+
+---
+
+## Interactions
+
+### Click Events
+
+Add clickable elements to nodes:
+
+#### Callback Function
+```mermaid
+flowchart LR
+    A-->B
+    click A callback "Tooltip for A"
+```
+
+```javascript
+const callback = function() {
+    alert('A callback was triggered');
+}
+```
+
+#### External Link
+```mermaid
+flowchart LR
+    A-->B
+    click A "https://www.github.com" "Navigate to GitHub"
+```
+
+#### Function Call
+```mermaid
+flowchart LR
+    A-->B
+    click A call callback() "Tooltip"
+```
+
+### Link Targets
+
+Specify how links open:
+
+```mermaid
+flowchart LR
+    A-->B
+    click A "https://www.github.com" _blank
+```
+
+**Target options:**
+- `_self` - Same frame (default)
+- `_blank` - New window/tab
+- `_parent` - Parent frame
+- `_top` - Full window
+
+**Security Note:** Click interactions are disabled with `securityLevel='strict'` and enabled with `securityLevel='loose'`.
+
+---
+
+## Special Characters and Escaping
+
+### Using Quotes
+
+Wrap text containing special characters in quotes:
+
+```mermaid
+flowchart LR
+    id1["This is the (text) in the box"]
+```
+
+Characters that need escaping: `()`, `{}`, `[]`, `:`, `;`, `|`
+
+### Entity Codes
+
+Use HTML entity codes for special characters:
+
+```mermaid
+flowchart LR
+    A["A double quote:#quot;"] --> B["A dec char:#9829;"]
+```
+
+**Common entity codes:**
+- `#quot;` - `"`
+- `#35;` - `#`
+- `#9829;` - ❤
+- `#amp;` - `&`
+- `#lt;` - `<`
+- `#gt;` - `>`
+
+---
+
+## FontAwesome Icons
+
+Embed FontAwesome icons in node text:
+
+### Basic Syntax
+```mermaid
+flowchart TD
+    B["fa:fa-twitter for peace"]
+    B-->C[fa:fa-ban forbidden]
+    B-->D(fa:fa-spinner)
+    B-->E(A fa:fa-camera-retro perhaps?)
+```
+
+### Icon Prefixes
+- `fa` - Standard icons
+- `fab` - Brand icons
+- `fas` - Solid style
+- `far` - Regular style
+- `fal` - Light style
+- `fad` - Duotone style
+- `fak` - Custom uploaded icons
+
+### Required CSS
+Include FontAwesome CSS in your HTML `<head>`:
+
+```html
+<link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css" rel="stylesheet"/>
+```
+
+---
+
+## Comments
+
+Add comments to your flowchart code (not rendered):
+
+```mermaid
+flowchart LR
+    %% This is a comment
+    A -- text --> B -- text2 --> C
+    %% Another comment
+```
+
+Comments must start with `%%` at the beginning of a line.
+
+---
+
+## Configuration
+
+### Renderer Selection
+
+Choose between rendering engines:
+
+```mermaid
+---
+config:
+  flowchart:
+    defaultRenderer: "elk"
+---
+flowchart TD
+    A --> B
+```
+
+**Available renderers:**
+- `dagre` (default) - Fast, suitable for most diagrams
+- `elk` - Better for large/complex diagrams
+
+### Width Adjustment
+
+Control diagram width programmatically:
+
+```javascript
+mermaid.flowchartConfig = {
+    width: "100%"
+}
+```
+
+### Markdown Auto-Wrap
+
+Disable automatic text wrapping in markdown strings:
+
+```mermaid
+---
+config:
+  markdownAutoWrap: false
+---
+flowchart LR
+    a("`The **cat**
+    in the hat`")
+```
+
+---
+
+## Complete Example
+
+Here's a comprehensive flowchart demonstrating multiple features:
+
+```mermaid
+flowchart TD
+    Start([Start Process]) --> Input[/Enter Data/]
+    Input --> Validate{Valid Data?}
+
+    Validate -->|Yes| Process[Process Data]
+    Validate -->|No| Error[Display Error]
+
+    Error --> Input
+
+    Process --> DB[(Save to Database)]
+    DB --> Check{Success?}
+
+    Check -->|Yes| Success([End Success])
+    Check -->|No| Retry{Retry?}
+
+    Retry -->|Yes| Process
+    Retry -->|No| Fail([End Failure])
+
+    style Start fill:#90EE90,stroke:#333,stroke-width:2px
+    style Success fill:#90EE90,stroke:#333,stroke-width:2px
+    style Fail fill:#FFB6C1,stroke:#333,stroke-width:2px
+    style Error fill:#FFB6C1,stroke:#333,stroke-width:2px
+
+    classDef decisionClass fill:#FFE4B5,stroke:#333,stroke-width:2px
+    class Validate,Check,Retry decisionClass
+```
+
+---
+
+## Common Patterns
+
+### Decision Tree
+```mermaid
+flowchart TD
+    A{Is it working?}
+    A -->|Yes| B[Don't touch it]
+    A -->|No| C{Did you touch it?}
+    C -->|Yes| D[Idiot!]
+    C -->|No| E{Does anyone know?}
+    E -->|Yes| F[You're screwed]
+    E -->|No| G[Hide it]
+```
+
+### Process Flow
+```mermaid
+flowchart LR
+    A([Start]) --> B[Initialize]
+    B --> C[Process Step 1]
+    C --> D[Process Step 2]
+    D --> E[Process Step 3]
+    E --> F([End])
+```
+
+### Approval Workflow
+```mermaid
+flowchart TD
+    Submit[Submit Request] --> Review{Manager Review}
+    Review -->|Approved| Finance{Finance Check}
+    Review -->|Rejected| Notify1[Notify Requester]
+    Finance -->|Approved| Execute[Execute]
+    Finance -->|Rejected| Notify2[Notify Requester]
+    Execute --> Complete([Complete])
+```
+
+---
+
+## Important Warnings
+
+### Reserved Words
+- **"end" keyword**: Capitalize it (`End`, `END`) or wrap in quotes to avoid breaking diagrams
+  ```mermaid
+  flowchart LR
+      A --> End
+  ```
+
+- **"o" and "x" at line start**: Add spaces or capitalize to prevent creating circle/cross edges
+  ```mermaid
+  flowchart LR
+      A --> B
+      %% Not: o--> (creates circle edge)
+      %% Use: O--> or add space
+  ```
+
+### Security Considerations
+- Click interactions are disabled with `securityLevel='strict'`
+- Enable with `securityLevel='loose'` when needed (only in trusted environments)
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Node not appearing:**
+- Verify node ID is defined before use
+- Check for typos in node references
+
+**Arrow not rendering:**
+- Verify arrow syntax (`-->`, `---`, `-.->`, `==>`)
+- Ensure both nodes exist
+
+**Text not displaying:**
+- Use quotes for special characters: `["text (with parens)"]`
+- Escape markdown properly with backticks
+
+**Subgraph not grouping:**
+- Ensure subgraph is declared before nodes
+- Check indentation and `end` keyword placement
+
+**Styling not applying:**
+- Verify style syntax (no spaces around `:`)
+- Check class names match definitions
+- Ensure classDef comes before class assignment
+
+**Validation failures:**
+- Run mermaid-cli to get specific error messages
+- Check for reserved words (like "end")
+- Verify all node IDs are properly defined
+
+---
+
+## Best Practices
+
+1. **Keep it simple**: Limit to 10-15 nodes per diagram for clarity
+2. **Use consistent shapes**: Follow standard conventions (diamonds for decisions, cylinders for databases)
+3. **Label edges**: Add text to arrows for clarity in complex flows
+4. **Group with subgraphs**: Organize related processes
+5. **Apply styling**: Use colors to highlight important paths or states
+6. **Test readability**: Ensure diagram is readable at documentation sizes
+7. **Comment your code**: Use `%%` comments to explain complex sections
+8. **Version control**: Treat diagrams as code and track changes
+9. **Split large diagrams**: Create multiple focused diagrams instead of one complex diagram
+10. **Validate syntax**: Always test with mermaid-cli before committing
+
+---
+
+This reference covers the complete Mermaid flowchart syntax. Use it to create professional process diagrams, decision trees, algorithm visualizations, and workflow documentation.